استفاده از AlloyDB Omni با MCP Toolbox برای ادغام عامل

۱. مقدمه

برای اینکه به عامل‌های هوش مصنوعی (مانند Antigravity CLI) دسترسی امن و ساختاریافته به پایگاه داده‌تان بدهید، می‌توانید AlloyDB Omni را با MCP Toolbox ویژه پایگاه‌های داده ادغام کنید.

AlloyDB Omni نسخه قابل‌بارگیری و کانتینری AlloyDB برای PostgreSQL است که برای اجرا در هر مکانی (در محل، در ایستگاه‌های کاری توسعه‌دهنده، در لبه، یا در فضای ابری) طراحی شده است و درعین‌حال عملکرد و سازگاری PostgreSQL در سطح سازمانی را ارائه می‌دهد.

‫MCP Toolbox ویژه پایگاه‌های داده یک سرور متن‌باز از Google است که «پروتکل بافتار مدل» (MCP) را پیاده‌سازی می‌کند تا ساختن ابزارهای هوش مصنوعی زایا را که با پایگاه‌های داده تعامل دارند آسان‌تر، سریع‌تر، و ایمن‌تر کند. این ابزار بین چارچوب هماهنگ‌سازی عامل شما و پایگاه داده‌تان قرار می‌گیرد و قابلیت‌های زیر را ارائه می‌دهد:

• توسعه ساده‌شده: ابزارهای پایگاه داده ازپیش‌ساخته یا سفارشی که با حداقل پیکربندی به نماینده شما متصل می‌شوند و می‌توانند در چندین نماینده یا چارچوب دوباره استفاده شوند.
• عملکرد بهتر: روال‌های مطلوب داخلی مانند ادغام اتصال و مدیریت چرخه حیات.
• امنیت بهبودیافته: مدیریت متمرکز اعتبارنامه و اصالت‌سنجی به‌گونه‌ای که نمایندگان به اعتبارنامه‌های پایگاه داده خام نیاز نداشته باشند.
• مشاهده‌پذیری سرتاسر: سنجه‌ها و ردیابی آماده استفاده با پشتیبانی داخلی برای OpenTelemetry.

در پایان این codelab، یک محفظه AlloyDB Omni درحال اجرا خواهید داشت که با داده‌های نمونه تجارت الکترونیک پر شده است، یک سرور MCP Toolbox که ۳۱ ابزار مدیریت و پُرسمان AlloyDB Omni ازپیش‌ساخته را ارائه می‌دهد، و یک عامل Antigravity CLI (agy) پیکربندی‌شده که قادر است طرح‌واره‌ها را بررسی کند، پُرسمان‌های SQL را اجرا کند، طرح‌های پُرسمان را تحلیل کند، و سلامت پایگاه داده را بااستفاده از پیام‌واره‌های زبان طبیعی تشخیص دهد.

پیش‌نیازها

• دسترسی به پروژه Google Cloud و Cloud Shell از کنسول Google Cloud، یا ایستگاه کاری Linux.
• Docker نصب شده است و درحال اجرا است.
• کارخواه psql PostgreSQL نصب شده باشد.
• curl و jq برای راه‌اندازی Antigravity CLI و MCP Toolbox نصب شده‌اند.

آنچه خواهید آموخت

• نحوه مستقر کردن و اجرا کردن حامل سرور پایگاه داده AlloyDB Omni بااستفاده از Docker.
• نحوه ایجاد کردن جدول‌ها، داده‌ها، و نمایه‌های نمونه در AlloyDB Omni.
• نحوه بارگیری، پیکربندی، و راه‌اندازی MCP Toolbox برای پایگاه‌های داده با مجموعه ابزار ازپیش‌ساخته alloydb-omni.
• نحوه پیکربندی Antigravity CLI به‌عنوان کارخواه MCP برای متصل شدن به سرور MCP Toolbox.
• نحوه استفاده از پیام‌واره‌های زبان طبیعی در Antigravity CLI برای بازرسی سلامت پایگاه داده، کاوش طرح‌واره‌ها، اجرای پُرسمان‌های SQL، تجزیه‌وتحلیل طرح‌های پُرسمان، و انجام عیب‌یابی‌های نگهداری.

آنچه نیاز خواهید داشت

• محیط پایانه فعال با Docker،‏ psql،‏ curl، و jq. می‌توانید از Google Cloud Shell استفاده کنید که این ابزارها ازقبل در آن نصب شده است.

۲. راه‌اندازی و الزامات

راه‌اندازی پروژه

ایجاد پروژه Google Cloud

1. در کنسول Google Cloud، در صفحه انتخابگر پروژه، پروژه Google Cloud را انتخاب یا ایجاد کنید.
2. تأیید کنید که صورت‌حساب برای پروژه Google Cloud شما فعال است. با نحوه بررسی فعال بودن صورت‌حساب در پروژه آشنا شوید.

شروع Cloud Shell

اگرچه می‌توانید AlloyDB Omni و MCP Toolbox را به‌صورت محلی در رایانه کیفی‌تان اجرا کنید، در این codelab می‌توانید از Google Cloud Shell استفاده کنید، محیط خط فرمانی که در فضای ابری اجرا می‌شود و Docker،‏ psql،‏ curl، و jq ازقبل در آن نصب شده است.

1. کنسول Google Cloud را باز کنید و روی فعال کردن Cloud Shell در نوارابزار بالا سمت چپ کلیک کنید.همچنین می‌توانید Cloud Shell را به یکی از روش‌های زیر باز کنید:
   • اگر از کنسول Google Cloud استفاده می‌کنید، G و سپس S را فشار دهید.
   • Cloud Shell را مستقیماً باز کنید.

معمولاً چند لحظه طول می‌کشد تا محیط آماده‌سازی شود و به آن متصل شوید. وقتی این عملیات تکمیل شد، چیزی شبیه به موارد زیر می‌بینید:

۳. آماده‌سازی و اجرای سرور پایگاه داده AlloyDB Omni

در این بخش، محفظه AlloyDB Omni Docker را می‌کشید و اجرا می‌کنید و آن را با داده‌های نمونه تجارت الکترونیک برای آزمایش کردن پر می‌کنید.

راه‌اندازی کردن سرور پایگاه داده 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. بااستفاده از Docker، محفظه AlloyDB Omni را در حالت جداشده شروع کنید:

   docker run --name alloydbomni \
       -e POSTGRES_PASSWORD=$ALLOYDB_OMNI_PASSWORD \
       -p $ALLOYDB_OMNI_PORT:$ALLOYDB_OMNI_PORT \
       -d google/alloydbomni:latest
   

3. بااستفاده از psql، بررسی کنید که محفظه درحال اجرا است و می‌توانید به سرور AlloyDB Omni متصل شوید:

   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;"
   

ایجاد داده‌های نمونه برای آزمایش

جدول‌های نمونه categories، products، customers، و orders را ایجاد کنید، رکوردهای آزمایشی را درج کنید، و نمایه‌ها را ایجاد کنید تا بتوانید بازرسی طرح‌واره، پُرسمان‌های SQL، و طرح‌های اجرای پُرسمان را ازطریق MCP Toolbox آزمایش کنید:

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', '[e-mail]'),
('Alan', 'Turing', '[e-mail]'),
('Grace', 'Hopper', '[e-mail]')
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

۴. راه‌اندازی سرور MCP Toolbox

در این بخش، باینری MCP Toolbox را بارگیری می‌کنید، تعاریف ابزار AlloyDB Omni ازپیش‌ساخته را پیکربندی می‌کنید، و سرور MCP Toolbox را راه‌اندازی می‌کنید.

بارگیری جعبه‌ابزار MCP

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 ۳۱ ابزار ازپیش‌ساخته ارائه می‌دهد، ازجمله ابزارهای کلیدی که در این 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 مراجعه کنید.

   نکته: سرور MCP Toolbox را در این برگه پایانه درحال اجرا نگه دارید و یک برگه پایانه جدید (+ در Cloud Shell) باز کنید تا دستورات باقی‌مانده در این codelab را اجرا کنید.

2. در برگه پایانه جدید، بررسی کنید که سرور MCP Toolbox درحال اجرا باشد و ابزارهای شما را ازطریق نقطه پایان JSON-RPC /mcp نمایش دهد:

   curl -X POST http://localhost:5000/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'
   

۵. پیکربندی کردن کارخواه MCP (رابط خط فرمان Antigravity)

در این بخش، 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) دنبال کنید و وقتی از شما پرسیده شد که آیا به دایرکتوری فعلی اعتماد دارید، بله، به این پوشه اعتماد دارم را انتخاب کنید.
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 برگردید.

‫۶. آزمایش کردن بااستفاده از پُرسمان‌ها برای AlloyDB Omni

اکنون که Antigravity CLI ازطریق MCP Toolbox به نمونه AlloyDB Omni شما متصل شده است، می‌توانید بااستفاده از پیام‌واره‌های زبان طبیعی با پایگاه داده‌تان تعامل کنید.

اجرای پُرسمان نمای کلی پایگاه داده

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 شما نگاشت می‌کند:

۱. نمای کلی و سلامت پایگاه داده

هدف آزمایش	پیام‌واره زبان طبیعی	ابزار فراخوانده شد
بررسی سیستم	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

۲. کاوش کاتالوگ و طرح‌واره

هدف آزمایش	پیام‌واره زبان طبیعی	ابزار فراخوانده شد
فهرست کردن جدول‌ها	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

۳. پُرسمان و فیلتر کردن داده‌ها (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

۴. عملکرد پُرسمان و توضیح طرح‌ها (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

۵. نگهداری و تشخیص خرابی پایگاه داده

هدف آزمایش	پیام‌واره زبان طبیعی	ابزار فراخوانده شد
تورم جدول	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

‫۷. مرتب‌سازی

پس‌از اتمام codelab، محفظه محلی و فرایندهایی را که شروع کرده‌اید پاک کنید.

1. با تایپ کردن /quit (یا دوبار فشار دادن Ctrl+D) از Antigravity CLI خارج شوید.
2. به برگه پایانه که سرور MCP Toolbox را اجرا می‌کند بروید و Ctrl+C را فشار دهید تا متوقف شود.
3. محفظه AlloyDB Omni Docker را متوقف و حذف کنید:

   docker stop alloydbomni
   docker rm alloydbomni
   

‫۸. تبریک می‌گوییم

بابت تکمیل codelab به شما تبریک می‌گوییم! شما با موفقیت AlloyDB Omni را در یک محفظه مستقر کردید، MCP Toolbox for Databases را با مجموعه ابزار ازپیش‌ساخته AlloyDB Omni پیکربندی کردید، و آن را با Antigravity CLI ادغام کردید تا پایگاه داده خود را بااستفاده از زبان طبیعی پُرسمان و مدیریت کنید.

آنچه پوشش داده‌اید

• نحوه استقرار و تأیید کردن محفظه AlloyDB Omni بااستفاده از Docker.
• نحوه پر کردن جدول‌ها و نمایه‌های نمونه برای آزمایش کردن گردش‌های کاری عامل.
• نحوه پیکربندی و اجرای MCP Toolbox for Databases با پیکربندی ابزارهای ازپیش‌ساخته alloydb-omni.
• نحوه متصل کردن Antigravity CLI به MCP Toolbox و اجرای پیام‌واره‌های زبان طبیعی برای کشف طرح‌واره، پُرسمان SQL، تجزیه‌وتحلیل طرح پُرسمان، و تشخیص خرابی پایگاه داده.

برای اطلاعات بیشتر، منابع زیر را ببینید:

• نمای کلی AlloyDB Omni
• مستندات MCP Toolbox ویژه پایگاه‌های داده
• مخزن GitHub برای MCP Toolbox
• مستندات Antigravity CLI

‫۹. نظرسنجی

چگونه از این آموزش استفاده خواهید کرد؟

فقط آن را بخوانید آن را بخوانید و تمرین‌ها را تکمیل کنید