استخدام AlloyDB Omni مع MCP Toolbox لدمج الوكلاء

1. مقدمة

لمنح وكلاء الذكاء الاصطناعي، مثل Antigravity CLI، وصولاً آمنًا ومنظّمًا إلى قاعدة بياناتك، يمكنك دمج AlloyDB Omni مع MCP Toolbox for Databases.

‫AlloyDB Omni هو إصدار قابل للتنزيل ومستند إلى حاويات من AlloyDB for PostgreSQL مصمّم للتشغيل في أي مكان، سواء في المؤسسة أو على محطات عمل المطوّرين أو على الأجهزة الطرفية أو في السحابة الإلكترونية، مع توفير أداء وتوافق PostgreSQL على مستوى المؤسسة.

‫MCP Toolbox for Databases هو خادم مفتوح المصدر من Google ينفّذ بروتوكول سياق النموذج (MCP) لتسهيل وتسريع وأمان إنشاء أدوات الذكاء الاصطناعي التوليدي التي تتفاعل مع قواعد البيانات. ويقع بين إطار عمل التنسيق الخاص بالوكيل وقاعدة البيانات، ويوفّر الإمكانات التالية:

  • تطوير مبسّط: أدوات قواعد بيانات مسبقة الصنع أو مخصّصة تتصل بوكيلك بأقل قدر من الإعدادات ويمكن إعادة استخدامها في عدة وكلاء أو أُطر عمل.
  • أداء أفضل: أفضل الممارسات المضمّنة، مثل تجميع الاتصالات وإدارة مراحل النشاط
  • أمان محسَّن: إدارة مركزية لبيانات الاعتماد والمصادقة كي لا يحتاج الوكلاء إلى بيانات اعتماد قاعدة البيانات الأولية
  • إمكانية تتبّع البيانات الشاملة: مقاييس وتتبُّع جاهزة للاستخدام مع دعم مدمج لـ OpenTelemetry.

في نهاية هذا الدرس التطبيقي حول الترميز، ستحصل على حاوية 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 وتشغيله.
  • تم تثبيت عميل PostgreSQL psql.
  • تم تثبيت 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 وتحليل خطط طلبات البحث وإجراء عمليات تشخيص الصيانة

المتطلبات

  • بيئة عمل في Terminal مع Docker وpsql وcurl وjq يمكنك استخدام Google Cloud Shell، الذي يأتي مثبّتًا مسبقًا مع هذه الأدوات.

2. الإعداد والمتطلبات

إعداد المشروع

إنشاء مشروع على Google Cloud

  1. في وحدة تحكّم Google Cloud، في صفحة اختيار المشروع، اختَر مشروعًا على السحابة الإلكترونية أو أنشِئ مشروعًا على السحابة الإلكترونية.
  2. تأكَّد من تفعيل الفوترة لمشروعك على Google Cloud. كيفية التحقّق من تفعيل الفوترة في مشروع

بدء Cloud Shell

على الرغم من أنّه يمكنك تشغيل AlloyDB Omni وMCP Toolbox محليًا على الكمبيوتر المحمول، يمكنك في هذا الدرس التطبيقي حول الترميز استخدام Google Cloud Shell، وهي بيئة سطر أوامر تعمل في السحابة الإلكترونية وتأتي مثبَّتة مسبقًا مع Docker وpsql وcurl وjq.

رمز تفعيل Cloud Shell

  1. افتح وحدة تحكّم Google Cloud وانقر على تفعيل Cloud Shell في شريط الأدوات في أعلى يسار الصفحة.يمكنك أيضًا فتح Cloud Shell بإحدى الطرق التالية:
    • إذا كنت تستخدم وحدة تحكّم Google Cloud، اضغط على G ثم على S.
    • افتح Cloud Shell مباشرةً.

عادةً ما يستغرق توفير البيئة والاتصال بها بضع دقائق. عند اكتمال هذه العملية، سيظهر لك ما يلي:

وحدة طرفية في Google Cloud Shell تعرض أنّ البيئة متصلة

3- إعداد خادم قاعدة بيانات 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. ابدأ حاوية 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;"

إنشاء عيّنات بيانات للاختبار

أنشِئ جداول نموذجية لـ 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', '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 أداة مُعدّة مسبقًا، بما في ذلك الأدوات الرئيسية الموضّحة في هذا الدرس التطبيقي حول الترميز:
    • 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. في علامة تبويب جديدة في Terminal، تأكَّد من أنّ خادم 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": {}}'

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) واختَر نعم، أثق بهذا المجلد عندما يُطلب منك تحديد ما إذا كنت تثق بالدليل الحالي.
  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. يربط الوكيل تلقائيًا كل طلب بالأداة المقابلة في مجموعة أدوات MCP في AlloyDB Omni:

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

طلب البحث Join

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- صيانة قاعدة البيانات وبيانات التشخيص

هدف الاختبار

طلب بلغة طبيعية

تم استدعاء الأداة

تضخُّم الجدول

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. تَنظيم

بعد الانتهاء من الدرس التطبيقي حول الترميز، عليك تنظيف الحاوية المحلية والعمليات التي بدأتها.

  1. اخرج من Antigravity CLI من خلال كتابة /quit (أو الضغط على Ctrl+D مرتين).
  2. انتقِل إلى علامة تبويب الوحدة الطرفية التي تشغّل خادم MCP Toolbox واضغط على Ctrl+C لإيقافه.
  3. أوقِف حاوية AlloyDB Omni Docker وأزِلها:
    docker stop alloydbomni
docker rm alloydbomni

8. تهانينا

تهانينا على إكمال الدرس التطبيقي حول الترميز. لقد نجحت في نشر AlloyDB Omni في حاوية، وضبطت MCP Toolbox for Databases باستخدام مجموعة أدوات AlloyDB Omni المُعدّة مسبقًا، ودمجتها مع Antigravity CLI لإرسال طلبات البحث إلى قاعدة البيانات وإدارتها باستخدام اللغة الطبيعية.

المواضيع التي تناولتها

  • كيفية نشر حاوية AlloyDB Omni والتحقّق منها باستخدام Docker
  • كيفية تعبئة الجداول والفهارس النموذجية لاختبار سير عمل الوكيل
  • كيفية ضبط MCP Toolbox for Databases وتشغيله باستخدام إعدادات أدوات alloydb-omni المُعدّة مسبقًا
  • كيفية ربط Antigravity CLI بـ MCP Toolbox وتنفيذ طلبات باللغة الطبيعية لاستكشاف المخططات وطلبات SQL وتحليل خطة طلبات البحث وتشخيصات قواعد البيانات

لمزيد من المعلومات، يُرجى الاطّلاع على المراجع التالية:

9. استطلاع

كيف ستستخدم هذا البرنامج التعليمي؟

قراءته فقط قراءته وإكمال التمارين