Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

Temsilci entegrasyonu için AlloyDB Omni'yi MCP Toolbox ile kullanma

1. Giriş

Antigravity CLI gibi yapay zeka ajanlarına veritabanınıza güvenli ve yapılandırılmış erişim sağlamak için AlloyDB Omni'yi MCP Toolbox for Databases ile entegre edebilirsiniz.

AlloyDB Omni, AlloyDB for PostgreSQL'in indirilebilir ve container mimarisine alınmış bir sürümüdür. Şirket içinde, geliştirici iş istasyonlarında, uçta veya bulutta her yerde çalışacak şekilde tasarlanmıştır. Ayrıca kurumsal düzeyde PostgreSQL performansı ve uyumluluğu sunar.

MCP Toolbox for Databases, veritabanlarıyla etkileşim kuran üretken yapay zeka araçları oluşturmayı daha kolay, hızlı ve güvenli hale getirmek için Model Context Protocol'ü (MCP) uygulayan, Google'ın açık kaynaklı bir sunucusudur. Temsilcinizin düzenleme çerçevesi ile veritabanınız arasında yer alır ve aşağıdaki özellikleri sunar:

Basitleştirilmiş geliştirme: Temsilcinize minimum yapılandırmayla bağlanan ve birden fazla temsilci veya çerçevede yeniden kullanılabilen önceden oluşturulmuş ya da özel veritabanı araçları.
Daha iyi performans: Bağlantı havuzu ve yaşam döngüsü yönetimi gibi yerleşik en iyi uygulamalar.
Gelişmiş güvenlik: Temsilcilerin ham veritabanı kimlik bilgilerine ihtiyaç duymaması için merkezi kimlik bilgisi ve kimlik doğrulama yönetimi.
Uçtan uca gözlemlenebilirlik: OpenTelemetry için yerleşik destekle kullanıma hazır metrikler ve izleme.

Bu codelab'i tamamladığınızda, örnek e-ticaret verileriyle doldurulmuş çalışan bir AlloyDB Omni container'ınız, önceden oluşturulmuş 31 AlloyDB Omni yönetim ve sorgu aracını sunan bir MCP Toolbox sunucunuz ve doğal dil istemlerini kullanarak şemaları inceleyebilen, SQL sorguları çalıştırabilen, sorgu planlarını analiz edebilen ve veritabanı durumunu teşhis edebilen yapılandırılmış bir Antigravity CLI (agy) temsilciniz olacak.

Temsilciden MCP istemcisine (Antigravity CLI), MCP Araç Kutusu'na ve AlloyDB Omni'ye kadar uçtan uca iş akışını gösteren mimari diyagramı

Ön koşullar

Google Cloud Console'dan veya Linux iş istasyonundan bir Google Cloud projesine ve Cloud Shell'e erişim.
Docker yüklü ve çalışıyor olmalıdır.
psql PostgreSQL istemcisi yüklü.
Antigravity CLI ve MCP Toolbox'ı kurmak için curl ve jq yüklendi.

Neler öğreneceksiniz?

Docker'ı kullanarak AlloyDB Omni veritabanı sunucusu kapsayıcısı dağıtma ve çalıştırma
AlloyDB Omni'de örnek tablolar, veriler ve dizinler oluşturma
Önceden oluşturulmuş alloydb-omni araç setiyle Veritabanları için MCP Araç Kutusu'nu indirme, yapılandırma ve başlatma
Antigravity CLI'yı MCP Toolbox sunucusuna bağlanmak için MCP istemcisi olarak yapılandırma
Veritabanı durumunu incelemek, şemaları keşfetmek, SQL sorguları çalıştırmak, sorgu planlarını analiz etmek ve bakım teşhisleri gerçekleştirmek için Antigravity CLI'da doğal dil istemlerini kullanma

İhtiyacınız olanlar

Docker, psql, curl ve jq içeren çalışan bir terminal ortamı Bu araçların önceden yüklü olduğu Google Cloud Shell'i kullanabilirsiniz.

2. Kurulum ve şartlar

Proje ayarlama

Google Cloud projesi oluşturma

Google Cloud Console'da, proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
Google Cloud projeniz için faturalandırmanın etkinleştirildiğini doğrulayın. Bir projede faturalandırmanın etkin olup olmadığını nasıl kontrol edeceğinizi öğrenin.

Cloud Shell'i Başlatma

AlloyDB Omni ve MCP Toolbox'ı dizüstü bilgisayarınızda yerel olarak çalıştırabilirsiniz. Ancak bu codelab'de, bulutta çalışan ve Docker, psql, curl ve jq önceden yüklenmiş olarak gelen bir komut satırı ortamı olan Google Cloud Shell'i kullanabilirsiniz.

Cloud Shell'i etkinleştirme simgesi

Google Cloud Console'u açın ve sağ üstteki araç çubuğunda Cloud Shell'i etkinleştir'i tıklayın.Cloud Shell'i aşağıdaki yöntemlerden biriyle de açabilirsiniz:
- Google Cloud konsolunu kullanıyorsanız G ve ardından S tuşlarına basın.
- Cloud Shell'i doğrudan açın.

Birkaç saniye içinde ortamın temel hazırlığı yapılır ve bağlantı kurulur. Bu işlem tamamlandığında aşağıdakine benzer bir sonuç görürsünüz:

Ortamın bağlandığını gösteren Google Cloud Shell terminali

3. AlloyDB Omni veritabanı sunucusunu hazırlama ve çalıştırma

Bu bölümde, AlloyDB Omni Docker container'ını alıp çalıştıracak ve test için örnek e-ticaret verileriyle dolduracaksınız.

AlloyDB Omni veritabanı sunucusunu başlatma

AlloyDB Omni ana makineniz, bağlantı noktanız, veritabanınız, kullanıcınız ve oluşturulan şifreniz için ortam değişkenleri tanımlayın:

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"

Docker'ı kullanarak AlloyDB Omni container'ını ayrılmış modda başlatın:

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

Kapsayıcının çalıştığını ve psql kullanarak AlloyDB Omni sunucusuna bağlanabildiğinizi doğrulayın:

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

Test için örnek veriler oluşturma

MCP Toolbox aracılığıyla şema incelemesini, SQL sorgularını ve sorgu yürütme planlarını test edebilmek için örnek categories, products, customers ve orders tabloları oluşturun, test kayıtları ekleyin ve dizinler oluşturun:

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 sunucusunu başlatma

Bu bölümde, MCP Araç Kutusu ikili programını indirecek, önceden oluşturulmuş AlloyDB Omni araç tanımlarını yapılandıracak ve MCP Araç Kutusu sunucusunu başlatacaksınız.

MCP Toolbox'ı indirme

MCP Araç Kutusu için bir dizin oluşturun ve toolbox ikili programını indirin:

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 sunucusunu yapılandırma ve başlatma

Önceden oluşturulmuş alloydb-omni.yaml araç yapılandırmasını indirin ve 5000 bağlantı noktasında MCP Araç Kutusu sunucusunu başlatın (daha önce dışa aktarılan ALLOYDB_OMNI_* ortam değişkenlerini kullanarak):
```
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 yapılandırması, bu codelab'de gösterilen temel araçlar da dahil olmak üzere önceden oluşturulmuş 31 araç sağlar:
- 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
Araçların tam listesi için GitHub'da alloydb-omni.yaml sayfasına bakın.
İpucu: MCP Toolbox sunucusunu bu terminal sekmesinde çalışır durumda bırakın ve bu codelab'deki kalan komutları çalıştırmak için yeni bir terminal sekmesi (Cloud Shell'de +) açın.

Yeni bir terminal sekmesinde, MCP Toolbox sunucusunun çalıştığını ve araçlarınızı JSON-RPC /mcp uç noktası üzerinden sunduğunu doğrulayın:

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

5. MCP istemcisini (Antigravity CLI) yapılandırma

Bu bölümde, Antigravity CLI'yı (agy) yükleyecek ve MCP Toolbox sunucunuza bağlanacak şekilde yapılandıracaksınız.

Antigravity CLI'yı yükleme

Henüz yüklenmemişse Antigravity CLI (agy) yükleyicisini indirip çalıştırın ve sürümü doğrulayın:

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'yı yapılandırma

MCP Toolbox sunucu girişini istemcinizin MCP yapılandırma dosyasına (ör. Antigravity CLI için ~/.gemini/config/mcp_config.json, Claude Code için .cursor/mcp.json, .vscode/mcp.json, claude_desktop_config.json veya .mcp.json) ekleyin.

Antigravity CLI'yı 5000 bağlantı noktasında çalışan MCP Toolbox HTTP sunucusuna bağlamak için agy mcp add komutunu çalıştırın ve girişi agy mcp list ile doğrulayın:
```
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
```
Bu komut, alloydb-omni sunucu yapılandırmasını ~/.gemini/config/mcp_config.json dosyasına yazar:
```
{
  "mcpServers": {
    "alloydb-omni": {
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}
```

Yapılandırmayı doğrulayın

Antigravity CLI'yı başlatın:
```
agy
```
agy uygulamasını ilk kez başlatıyorsanız oturum açmak için ekranda verilen talimatları uygulayın (Google OAuth veya Google Cloud projesiyle) ve mevcut dizine güvenilip güvenilmeyeceği sorulduğunda Evet, bu klasöre güveniyorum'u seçin.

Antigravity CLI isteminde /mcp girerek MCP Servers (MCP Sunucuları) panelini açın ve alloydb-omni sunucusunun bağlı olduğunu doğrulayın:

/mcp

Çıkış şuna benzer:

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

MCP Servers (MCP Sunucuları) panelini kapatıp Antigravity CLI istemine dönmek için Esc tuşuna basın.

6. AlloyDB Omni için sorguları kullanarak test etme

Antigravity CLI, MCP Toolbox aracılığıyla AlloyDB Omni örneğinize bağlandığına göre artık doğal dil istemlerini kullanarak veritabanınızla etkileşim kurabilirsiniz.

Veritabanına genel bakış sorgusu çalıştırma

Antigravity CLI isteminde mevcut veritabanına genel bir bakış isteyin:

Give me an overview of the current database.

Aracı çağırmanız istendiğinde Evet'i (veya bu sohbette Evet ve her zaman izin ver'i) seçin. Çıkış şuna benzer:

> 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)

Kategoriye göre test örnekleri

Antigravity CLI'ya aşağıdaki doğal dil isteklerini girin. Temsilci, her isteği AlloyDB Omni MCP araç setinizdeki ilgili araçla otomatik olarak eşler:

1. Veritabanına genel bakış ve veritabanı sağlığı

Test hedefi	Doğal dilde istem	Araç çağrıldı
Sistem kontrolü	`Give me an overview of the current database.`	`database_overview`
Etkin bağlantılar	`What queries are currently running on the database?`	`list_active_queries`
Yüklenen uzantılar	`What extensions are installed in this database?`	`list_installed_extensions`
Kullanılabilir uzantılar	`What extensions are available that I can install?`	`list_available_extensions`

2. Şema ve katalog keşfi

Test hedefi	Doğal dilde istem	Araç çağrıldı
Tabloları listeleme	`Show me all the tables in the current database.`	`list_tables`
Dizinleri inceleme	`List all indexes in the database and which tables they belong to.`	`list_indexes`
Görünümleri keşfetme	`What views are available in the public schema?`	`list_views`
Tablo tetikleyicilerini kontrol etme	`Show me the triggers defined on the orders table.`	`list_triggers`

3. Veri sorgulama ve filtreleme (`execute_sql`)

Test hedefi	Doğal dilde istem	Araç çağrıldı
Toplu sorgu	`Show me the 3 most expensive products in the 'Laptops' category.`	`execute_sql`
Birleştirme sorgusu	`Find all customers who have placed an order in the last 6 months.`	`execute_sql`
Eşleşmeyen kayıtlar	`Which customers haven't placed any orders yet?`	`execute_sql`

4. Sorgu performansı ve açıklama planları (`get_query_plan`)

Test hedefi	Doğal dilde istem	Araç çağrıldı
Planı açıklama	`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`
Dizin doğrulama	`Get the query plan for SELECT * FROM products WHERE category = 'Audio' and tell me if it uses the index.`	`get_query_plan`

5. Veritabanı bakımı ve teşhisleri

Test hedefi	Doğal dilde istem	Araç çağrıldı
Tablo şişmesi	`List the top five most bloated tables.`	`list_top_bloated_tables`
Kilit anlaşmazlığı	`Show me if there are any active locks or blocked transactions.`	`list_locks`
Autovacuum ayarları	`Show me the current autovacuum configuration.`	`list_autovacuum_configurations`
Geçersiz dizinler	`Check for any invalid indexes in the database.`	`list_invalid_indexes`

7. Temizleme

Codelab'i tamamladıktan sonra yerel kapsayıcıyı ve başlattığınız işlemleri temizleyin.

/quit yazarak (veya Ctrl+D tuşuna iki kez basarak) Antigravity CLI'dan çıkın.
MCP Toolbox sunucusunu çalıştıran terminal sekmesine geçin ve sunucuyu durdurmak için Ctrl+C tuşlarına basın.
AlloyDB Omni Docker container'ını durdurup kaldırın:
```
docker stop alloydbomni
docker rm alloydbomni
```

8. Tebrikler

Tebrikler, codelab'i tamamladınız. AlloyDB Omni'yi bir container'da başarıyla dağıttınız, MCP Toolbox for Databases'i önceden oluşturulmuş AlloyDB Omni araç setiyle yapılandırdınız ve doğal dil kullanarak veritabanınızı sorgulamak ve yönetmek için Antigravity CLI ile entegre ettiniz.

İşlediğiniz konular

Docker kullanarak AlloyDB Omni kapsayıcısı dağıtma ve doğrulama
Temsilci iş akışlarını test etmek için örnek tabloları ve dizinleri doldurma
Veritabanları için MCP Araç Kutusu'nu önceden oluşturulmuş alloydb-omni araç yapılandırmasıyla yapılandırma ve çalıştırma
Antigravity CLI'yı MCP Toolbox'a bağlama ve şema keşfi, SQL sorgulama, sorgu planı analizi ve veritabanı teşhisi için doğal dil istemleri çalıştırma

Daha fazla bilgi için aşağıdaki kaynaklara bakın:

9. Anket

Bu eğitimden nasıl yararlanacaksınız?

Yalnızca okudum

Okudum ve alıştırmaları tamamladım