איך משתמשים ב-AlloyDB Omni עם MCP Toolbox לשילוב סוכנים

1. מבוא

כדי לתת לסוכני AI, כמו Antigravity CLI, גישה מאובטחת ומובנית למסד הנתונים, אתם יכולים לשלב את AlloyDB Omni עם MCP Toolbox for Databases.

‫AlloyDB Omni היא גרסה של AlloyDB ל-PostgreSQL שאפשר להוריד ולהריץ בכל מקום – באופן מקומי, בתחנות עבודה של מפתחים, בקצה הרשת או בענן – תוך שמירה על ביצועים ותאימות ברמה שמתאימה לארגונים.

‫MCP Toolbox for Databases הוא שרת קוד פתוח של Google שמטמיע את Model Context Protocol‏ (MCP) כדי שיהיה קל, מהיר ובטוח יותר ליצור כלי AI גנרטיביים שמתקשרים עם מסדי נתונים. הוא נמצא בין מסגרת התזמור של הסוכן לבין מסד הנתונים, ומספק את היכולות הבאות:

  • פיתוח פשוט יותר: כלי מסד נתונים מובנים או בהתאמה אישית שמתחברים לנציג שלכם עם הגדרה מינימלית, ואפשר להשתמש בהם שוב בכמה נציגים או מסגרות.
  • ביצועים משופרים: שיטות מומלצות מובנות כמו מאגר חיבורים וניהול מחזור חיים.
  • אבטחה משופרת: ניהול מרכזי של פרטי כניסה ואימות, כך שהסוכנים לא צריכים פרטי כניסה גולמיים למסד הנתונים.
  • ניראות מקצה לקצה: מדדים ומעקב מוכנים לשימוש עם תמיכה מובנית ב-OpenTelemetry.

בסיום ה-Codelab הזה, יהיה לכם קונטיינר AlloyDB Omni פועל שמאוכלס בנתונים לדוגמה של מסחר אלקטרוני, שרת MCP Toolbox שחושף 31 כלי ניהול ושאילתות מובנים של AlloyDB Omni, וסוכן Antigravity CLI (agy) מוגדר שיכול לבדוק סכימות, להריץ שאילתות SQL, לנתח תוכניות לביצוע שאילתות ולאבחן את תקינות מסד הנתונים באמצעות הנחיות בשפה טבעית.

דיאגרמת ארכיטקטורה שמראה את תהליך העבודה מקצה לקצה, מהנציג ללקוח MCP (‏Antigravity CLI) ל-MCP Toolbox ל-AlloyDB Omni

דרישות מוקדמות

  • גישה לפרויקט בענן ב-Google Cloud ול-Cloud Shell ממסוף Google Cloud, או לתחנת עבודה של Linux.
  • ‫Docker מותקן ופועל.
  • הלקוח psql של PostgreSQL מותקן.
  • ‫curl ו-jq מותקנים כדי להגדיר את Antigravity CLI ו-MCP Toolbox.

מה תלמדו

  • איך פורסים ומריצים קונטיינר של שרת מסד נתונים של AlloyDB Omni באמצעות Docker.
  • איך יוצרים טבלאות, נתונים ואינדקסים לדוגמה ב-AlloyDB Omni.
  • איך להוריד, להגדיר ולהפעיל את MCP Toolbox for Databases באמצעות ערכת הכלים המוכנה מראש של alloydb-omni.
  • איך מגדירים את Antigravity CLI כלקוח MCP כדי להתחבר לשרת MCP Toolbox.
  • איך משתמשים בהנחיות בשפה טבעית ב-Antigravity CLI כדי לבדוק את תקינות מסד הנתונים, לחקור סכימות, להריץ שאילתות SQL, לנתח תוכניות לביצוע שאילתות ולבצע אבחון תחזוקה.

הדרישות

  • סביבת טרמינל פעילה עם Docker,‏ psql,‏ curl ו-jq. אתם יכולים להשתמש ב-Google Cloud Shell, שבו הכלים האלה מותקנים מראש.

2. הגדרה ודרישות

הגדרת הפרויקט

יצירת פרויקט של Google Cloud

  1. במסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט או יוצרים פרויקט חדש.
  2. מוודאים שהחיוב מופעל בפרויקט בענן ב-Google Cloud. כך בודקים אם החיוב מופעל בפרויקט

הפעלת Cloud Shell

אפשר להריץ את AlloyDB Omni ואת MCP Toolbox באופן מקומי במחשב הנייד, אבל ב-Codelab הזה אתם יכולים להשתמש ב-Google Cloud Shell, סביבת שורת פקודה שפועלת בענן ומותקנים בה מראש Docker,‏ psql,‏ curl ו-jq.

סמל להפעלת Cloud Shell

  1. פותחים את מסוף Google Cloud ולוחצים על Activate Cloud Shell בסרגל הכלים שבפינה הימנית העליונה.אפשר גם לפתוח את Cloud Shell באחת מהדרכים הבאות:
    • אם משתמשים במסוף Google Cloud, לוחצים על G ואז על S.
    • פותחים את Cloud Shell ישירות.

בדרך כלל, הקצאת הסביבה וההתחברות אליה נמשכות כמה דקות. בסיום הפעולה, יופיע משהו דומה לזה:

מסוף Google Cloud Shell שמראה שהסביבה התחברה

3. הכנה והפעלה של שרת מסד הנתונים של AlloyDB Omni

בקטע הזה, תשלפו ותריצו את מאגר Docker של AlloyDB Omni ותאכלסו אותו בנתוני מסחר אלקטרוני לדוגמה לצורך בדיקה.

הפעלת שרת מסד הנתונים של AlloyDB Omni

  1. מגדירים משתני סביבה למארח, ליציאה, למסד הנתונים, למשתמש ולסיסמה שנוצרה ב-AlloyDB Omni:
    export ALLOYDB_OMNI_HOST="127.0.0.1"
export ALLOYDB_OMNI_PORT="5432"
export ALLOYDB_OMNI_DATABASE="postgres"
export ALLOYDB_OMNI_USER="postgres"
export ALLOYDB_OMNI_PASSWORD="$(openssl rand -hex 8)@1aA"
echo "Your generated AlloyDB Omni postgres password is: $ALLOYDB_OMNI_PASSWORD"
  2. מפעילים את מאגר AlloyDB Omni במצב מנותק באמצעות Docker:
    docker run --name alloydbomni \
    -e POSTGRES_PASSWORD=$ALLOYDB_OMNI_PASSWORD \
    -p $ALLOYDB_OMNI_PORT:$ALLOYDB_OMNI_PORT \
    -d google/alloydbomni:latest
  3. מוודאים שהקונטיינר פועל ושאפשר להתחבר לשרת AlloyDB Omni באמצעות psql:
    docker ps -a
until docker exec alloydbomni pg_isready -U "$ALLOYDB_OMNI_USER" -d "$ALLOYDB_OMNI_DATABASE"; do sleep 2; done
PGPASSWORD=$ALLOYDB_OMNI_PASSWORD psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE -c "SELECT 1;"

יצירת נתונים לדוגמה לבדיקה

כדי לבדוק את בדיקת הסכימה, שאילתות SQL ותוכניות להרצת שאילתות באמצעות MCP Toolbox, יוצרים טבלאות לדוגמה של categories,‏ products,‏ customers ו-orders, מוסיפים רשומות לבדיקה ויוצרים אינדקסים:

PGPASSWORD="$ALLOYDB_OMNI_PASSWORD" psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE << 'EOF'
CREATE TABLE IF NOT EXISTS categories (
    category_id SERIAL PRIMARY KEY,
    name VARCHAR(50) UNIQUE NOT NULL
);

CREATE TABLE IF NOT EXISTS products (
    product_id SERIAL PRIMARY KEY,
    product_name VARCHAR(100) UNIQUE NOT NULL,
    category VARCHAR(50) NOT NULL,
    price NUMERIC(10, 2) NOT NULL,
    stock INT DEFAULT 0
);

CREATE TABLE IF NOT EXISTS customers (
    customer_id SERIAL PRIMARY KEY,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    email VARCHAR(100) UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS orders (
    order_id SERIAL PRIMARY KEY,
    customer_id INT REFERENCES customers(customer_id),
    order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    total_amount NUMERIC(10, 2)
);

-- Insert sample rows
INSERT INTO categories (name) VALUES
('Smartphones'),
('Laptops'),
('Audio')
ON CONFLICT DO NOTHING;

INSERT INTO products (product_name, category, price, stock) VALUES
('Pixel 9 Pro', 'Smartphones', 999.00, 50),
('MacBook Pro M3', 'Laptops', 1999.00, 20),
('ThinkPad X1 Carbon', 'Laptops', 1450.00, 35),
('Dell XPS 15', 'Laptops', 1700.00, 15),
('Bose QuietComfort', 'Audio', 349.00, 100)
ON CONFLICT DO NOTHING;

INSERT INTO customers (first_name, last_name, email) VALUES
('Ada', 'Lovelace', 'ada@example.com'),
('Alan', 'Turing', 'alan@example.com'),
('Grace', 'Hopper', 'grace@example.com')
ON CONFLICT DO NOTHING;

INSERT INTO orders (order_id, customer_id, total_amount, order_date) VALUES
(1, 1, 999.00, pg_catalog.now() - INTERVAL '7 months'),
(2, 2, 349.00, pg_catalog.now() - INTERVAL '1 month')
ON CONFLICT DO NOTHING;

CREATE INDEX IF NOT EXISTS idx_products_category ON products(category);
CREATE INDEX IF NOT EXISTS idx_orders_customer ON orders(customer_id);
EOF

4. הפעלת שרת MCP Toolbox

בקטע הזה תורידו את הקובץ הבינארי של MCP Toolbox, תגדירו את הגדרות הכלים המוכנות מראש של AlloyDB Omni ותפעילו את שרת MCP Toolbox.

הורדת MCP Toolbox

  1. יוצרים ספרייה ל-MCP Toolbox ומורידים את הקובץ הבינארי של toolbox:
    mkdir -p ~/mcp/tools
cd ~/mcp
curl -L -O https://storage.googleapis.com/genai-toolbox/v0.31.0/linux/amd64/toolbox
chmod +x toolbox
./toolbox --version

הגדרה והפעלה של שרת MCP Toolbox

  1. מורידים את הגדרת הכלים המוכנה מראש של alloydb-omni.yaml ומפעילים את שרת MCP Toolbox ביציאה 5000 (באמצעות משתני הסביבה של ALLOYDB_OMNI_* שיוצאו קודם):
    curl -sL --create-dirs -o "tools/alloydb-omni.yaml" "https://raw.githubusercontent.com/googleapis/mcp-toolbox/v0.31.0/internal/prebuiltconfigs/tools/alloydb-omni.yaml"
# Remove the trailing group definition block and YAML document separator for --config-folder compatibility
sed -i '/^kind: group/,$d' tools/alloydb-omni.yaml
sed -i '${/---/d;}' tools/alloydb-omni.yaml

./toolbox --config-folder ./tools/ --port 5000 --address 127.0.0.1
    ההגדרה alloydb-omni.yaml מספקת 31 כלים מובנים, כולל הכלים העיקריים שהודגמו ב-Codelab הזה:
    • execute_sql
    • get_query_plan
    • database_overview
    • list_active_queries
    • list_tables, list_indexes, list_views, list_triggers
    • list_top_bloated_tables, list_locks, list_autovacuum_configurations, list_invalid_indexes
    לרשימת הכלים המלאה, ראו alloydb-omni.yaml ב-GitHub.
  2. בכרטיסייה חדשה של הטרמינל, מוודאים ששרת MCP Toolbox פועל וחושף את הכלים שלכם דרך נקודת הקצה /mcp של JSON-RPC:
    curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

5. הגדרת לקוח ה-MCP‏ (Antigravity CLI)

בקטע הזה תתקינו את Antigravity CLI (agy) ותגדירו אותו להתחבר לשרת MCP Toolbox.

התקנת Antigravity CLI

  1. אם הוא עדיין לא מותקן, מורידים ומפעילים את מנהל ההתקנה של Antigravity CLI‏ (agy) ובודקים את הגרסה:
    curl -fsSL https://antigravity.google/cli/install.sh -o /tmp/install.sh
bash /tmp/install.sh
rm -f /tmp/install.sh

# If prompted by the installer, add ~/.local/bin to your PATH:
export PATH="$HOME/.local/bin:$PATH"

# Verify the installation
agy --version

הגדרת Antigravity CLI

מוסיפים את רשומת השרת של MCP Toolbox לקובץ התצורה של MCP בלקוח (למשל ~/.gemini/config/mcp_config.json ל-Antigravity CLI,‏ .cursor/mcp.json,‏ .vscode/mcp.json,‏ claude_desktop_config.json או .mcp.json ל-Claude Code).

  1. כדי לחבר את Antigravity CLI לשרת ה-HTTP הפעיל של MCP Toolbox ביציאה 5000, מריצים את agy mcp add ומאמתים את הרשומה באמצעות agy mcp list:
    export MCP_SERVER="127.0.0.1"
export MCP_PORT="5000"

agy mcp add alloydb-omni "http://${MCP_SERVER}:${MCP_PORT}/mcp"
agy mcp list
    הפקודה הזו כותבת את הגדרת השרת של alloydb-omni אל ~/.gemini/config/mcp_config.json:
    {
  "mcpServers": {
    "alloydb-omni": {
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}

אימות ההגדרות האישיות

  1. מפעילים את Antigravity CLI:
    agy
    אם זו הפעם הראשונה שאתם מפעילים את agy, פעלו לפי ההנחיות במסך כדי להיכנס (באמצעות Google OAuth או פרויקט בענן של Google Cloud) ובחרו באפשרות Yes, I trust this folder כשתישאלו אם אתם סומכים על הספרייה הנוכחית.
  2. בשורת הפקודה של Antigravity CLI, מזינים /mcp כדי לפתוח את החלונית שרתי MCP ולוודא ש-alloydb-omni מחובר:
    /mcp
    הפלט אמור להיראות כך:
    MCP Servers

Configured (~/.gemini/config/mcp_config.json)
>  ✓ alloydb-omni  Tools: database_overview, execute_sql, get_column_cardinality, get_query_plan, list_active_queries, +26 more

Keyboard: ↑/↓ Navigate  enter Actions
  3. מקישים על Esc כדי לסגור את החלונית שרתי MCP ולחזור להנחיה של Antigravity CLI.

6. בדיקה באמצעות שאילתות ב-AlloyDB Omni

עכשיו, כש-Antigravity CLI מחובר למכונה של AlloyDB Omni דרך MCP Toolbox, אתם יכולים לקיים אינטראקציה עם מסד הנתונים באמצעות הנחיות בשפה טבעית.

הרצת שאילתה של סקירה כללית של מסד הנתונים

  1. בהנחיה של Antigravity CLI, מבקשים סקירה כללית של מסד הנתונים הנוכחי:
    Give me an overview of the current database.
    כשמוצגת בקשה לאשר את הפעלת הכלי, לוחצים על כן (או על כן, ובלי הגבלת שימוש בשיחה הזו). הפלט אמור להיראות כך:
    > Give me an overview of the current database.

● alloydb-omni/database_overview(Database overview check) (ctrl+o to expand)

  Here is an overview of the current AlloyDB Omni database instance:

  ### Database Overview
  • Instance / Engine: PostgreSQL 17.9 (AlloyDB Omni)
  • Role: Primary (is_replica: false)
  • Uptime: ~7 hours, 57 minutes
  • Connected Database: postgres
  • Connected User: postgres
  • Connections: 11 current / 100 max (1 active, 11% used)

  ### Databases in Instance
  • postgres
  • alloydbadmin (~15.74 MB)
  • alloydbmetadata (~14.82 MB)

דוגמאות לבדיקות לפי קטגוריה

מזינים ב-Antigravity CLI את ההנחיות הבאות בשפה טבעית. הנציג ממפה באופן אוטומטי כל בקשה לכלי המתאים ב-AlloyDB Omni MCP:

1. סקירה כללית ותקינות של מסד הנתונים

יעד הבדיקה

הנחיה בשפה טבעית

הכלי הופעל

בדיקת המערכת

Give me an overview of the current database.

database_overview

חיבורים פעילים

What queries are currently running on the database?

list_active_queries

תוספים מותקנים

What extensions are installed in this database?

list_installed_extensions

תוספים זמינים

What extensions are available that I can install?

list_available_extensions

2. עיון בסכימה ובקטלוג

יעד הבדיקה

הנחיה בשפה טבעית

הכלי הופעל

הצגת רשימה של טבלאות

Show me all the tables in the current database.

list_tables

בדיקת אינדקסים

List all indexes in the database and which tables they belong to.

list_indexes

תצוגות מפורטות

What views are available in the public schema?

list_views

בדיקת הטריגרים של הטבלה

Show me the triggers defined on the orders table.

list_triggers

3. שאילתות וסינון של נתונים (execute_sql)

יעד הבדיקה

הנחיה בשפה טבעית

הכלי הופעל

שאילתה נצברת

Show me the 3 most expensive products in the 'Laptops' category.

execute_sql

שאילתת צירוף

Find all customers who have placed an order in the last 6 months.

execute_sql

רשומות ללא התאמה

Which customers haven't placed any orders yet?

execute_sql

4. ביצועי שאילתות ותוכניות הסבר (get_query_plan)

יעד הבדיקה

הנחיה בשפה טבעית

הכלי הופעל

הסבר על התוכנית

Explain the query plan for a query that finds all customers who have not placed an order in the last 6 months.

get_query_plan

אימות אינדקס

Get the query plan for SELECT * FROM products WHERE category = 'Audio' and tell me if it uses the index.

get_query_plan

5. תחזוקה ואבחון של מסד הנתונים

יעד הבדיקה

הנחיה בשפה טבעית

הכלי הופעל

Table bloat

List the top five most bloated tables.

list_top_bloated_tables

תחרות על נעילה

Show me if there are any active locks or blocked transactions.

list_locks

הגדרות Autovacuum

Show me the current autovacuum configuration.

list_autovacuum_configurations

אינדקסים לא תקינים

Check for any invalid indexes in the database.

list_invalid_indexes

7. הסרת המשאבים

בסיום ה-Codelab, צריך לנקות את הקונטיינר המקומי ואת התהליכים שהתחלתם.

  1. כדי לצאת מ-Antigravity CLI, מקלידים /quit (או לוחצים על Ctrl+D פעמיים).
  2. עוברים לכרטיסיית הטרמינל שבה פועל שרת MCP Toolbox ולוחצים על Ctrl+C כדי לעצור אותו.
  3. עוצרים ומסירים את מאגר הנתונים של AlloyDB Omni Docker:
    docker stop alloydbomni
docker rm alloydbomni

8. מזל טוב

כל הכבוד, סיימתם את ה-Codelab! פרסתם בהצלחה את AlloyDB Omni בקונטיינר, הגדרתם את MCP Toolbox for Databases באמצעות ערכת הכלים המובנית של AlloyDB Omni ושילבתם אותה עם Antigravity CLI כדי לשלוח שאילתות למסד הנתונים ולנהל אותו באמצעות שפה טבעית.

מה כבר למדתם

  • איך פורסים ומאמתים קונטיינר של AlloyDB Omni באמצעות Docker.
  • איך לאכלס טבלאות ואינדקסים לדוגמה כדי לבדוק Agentic Workflows.
  • איך להגדיר ולהפעיל את MCP Toolbox for Databases עם הגדרת הכלים המוכנים מראש של alloydb-omni.
  • איך מחברים את Antigravity CLI ל-MCP Toolbox ומריצים הנחיות בשפה טבעית כדי לגלות סכימות, להריץ שאילתות SQL, לנתח תוכניות לביצוע שאילתות ולבצע אבחון של מסדי נתונים.

מידע נוסף זמין במקורות המידע הבאים:

9. סקר

איך תשתמשו במדריך הזה?

רק קראתי אותו קראתי אותו וביצעתי את התרגילים