Codelab: Spanner MCP Sunucusu

1. Genel Bakış

Bu codelab'de, gemini-cli ve Google'ın Model Context Protocol (MCP) sunucularını kullanarak Spanner'da grafik sorgularının nasıl yayınlanacağı gösterilmektedir. Spanner Graph dahil olmak üzere Spanner'ın çok modelli veritabanını yönetilen MCP hizmetiyle entegre ederek karmaşık GQL (Graph Query Language) veya SQL sorgularını manuel olarak yazmadan tek bir veritabanında verilerinizdeki gizli ilişkileri (ör. sahtekarlık çemberleri veya tedarik zinciri bağımlılıkları) ortaya çıkarmak için doğal dili kullanabilirsiniz.

Öğrenecekleriniz

• MCP için Spanner Graph dahil olmak üzere Spanner çok modelli veritabanı oluşturma.
• Gemini CLI'ı yönetilen bir uzak Spanner hizmeti uç noktasına bağlama
• Grafik geçişleri ve kalıp eşleştirme işlemlerini ilişkisel işlemlerle birlikte gerçekleştirmek için doğal dili kullanarak GQL ile entegre edilmiş SQL'i otomatik olarak nasıl oluşturabilirsiniz?
• Yapay zeka iş akışlarında grafik verilerinin güvenliğini sağlama ile ilgili en iyi uygulamalar.

Ön koşullar

• Faturalandırmanın etkin olduğu bir Google Cloud projesi.
• Terminal erişimi (ör. Cloud Shell). Bu codelab'e göz atın.
• gcloud CLI'nin yüklenmiş ve kimliği doğrulanmış olması gerekir.
• Gemini CLI'ye erişim

NOT: Tüm komutları bir Unix terminalinde çalıştıracaksınız. Uygun kimlik doğrulama ile gcloud'a erişimi olan bir terminale erişmek için lütfen yukarıdaki ön koşulları inceleyin.

2. Spanner Multi-model Environment'ı ayarlama

Yönetilen MCP, veritabanı şeması önceden tanımlandığında en iyi şekilde çalışır. Spanner Graph örneklerini temel alarak bir finansal "Sahtekarlık Tespiti" grafiği oluşturacağız.

API'leri etkinleştir

export PROJECT_ID="YOUR_PROJECT_ID"

gcloud config set project ${PROJECT_ID}

# Enable Spanner's MCP endpoint
gcloud beta services mcp enable spanner.googleapis.com --project=${PROJECT_ID}

Veritabanı Şemasını Oluşturma

Veritabanı tabloları ve özellik grafiği içeren bir örnek ve veritabanı oluşturun. Bu şema, Hesaplar, Kişiler ve aralarındaki Transferler'i izler.

NOT: Bu DDL ifadelerini Spanner Studio'dan çalıştırabilirsiniz. GCP Console'dan Spanner veritabanı oluşturma ve sorgulama hakkında bilgi edinmek için lütfen bu bağlantıya bakın.

CREATE TABLE Account (
  id INT64 NOT NULL,
  create_time TIMESTAMP,
  is_blocked BOOL,
  nick_name STRING(MAX),
) PRIMARY KEY(id);

CREATE TABLE Person (
  id INT64 NOT NULL,
  name STRING(MAX),
  birthday TIMESTAMP,
  country STRING(MAX),
  city STRING(MAX),
) PRIMARY KEY(id);

CREATE TABLE AccountTransferAccount (
  id INT64 NOT NULL,
  to_id INT64 NOT NULL,
  amount FLOAT64,
  create_time TIMESTAMP NOT NULL,
  order_number STRING(MAX),
  FOREIGN KEY(to_id) REFERENCES Account(id),
) PRIMARY KEY(id, to_id, create_time),
  INTERLEAVE IN PARENT Account ON DELETE CASCADE;

CREATE TABLE PersonOwnAccount (
  id INT64 NOT NULL,
  account_id INT64 NOT NULL,
  create_time TIMESTAMP,
  FOREIGN KEY(account_id) REFERENCES Account(id),
) PRIMARY KEY(id, account_id),
  INTERLEAVE IN PARENT Person ON DELETE CASCADE;

CREATE PROPERTY GRAPH FinGraph
  NODE TABLES(
    Account
      KEY(id)
      LABEL Account PROPERTIES(
        create_time,
        id,
        is_blocked,
        nick_name),

    Person
      KEY(id)
      LABEL Person PROPERTIES(
        birthday,
        city,
        country,
        id,
        name)
  )
  EDGE TABLES(
    AccountTransferAccount
      KEY(id, to_id, create_time)
      SOURCE KEY(id) REFERENCES Account(id)
      DESTINATION KEY(to_id) REFERENCES Account(id)
      LABEL Transfers PROPERTIES(
        amount,
        create_time,
        id,
        order_number,
        to_id),

    PersonOwnAccount
      KEY(id, account_id)
      SOURCE KEY(id) REFERENCES Person(id)
      DESTINATION KEY(account_id) REFERENCES Account(id)
      LABEL Owns PROPERTIES(
        account_id,
        create_time,
        id)
  );

Verileri doldurma

Kişi Ekleme

INSERT INTO Person (id, name, birthday, country, city) VALUES
(1, 'Alex', '1990-01-01T00:00:00Z', 'USA', 'New York'),
(2, 'Lee', '1985-05-15T00:00:00Z', 'USA', 'San Francisco'),
(3, 'Dana', '1995-08-20T00:00:00Z', 'Canada', 'Vancouver'),
(4, 'Maria', '1992-04-15T00:00:00Z', 'USA', 'Chicago'),
(5, 'David', '1988-11-20T00:00:00Z', 'Canada', 'Toronto');

Hesap ekleme

INSERT INTO Account (id, create_time, is_blocked, nick_name) VALUES
(7, '2020-01-10T14:22:20.222Z', false, 'Vacation Fund'),
(16, '2020-01-28T01:55:09.206Z', true, 'Vacation Fund'),
(20, '2020-02-18T13:44:20.655Z', false, 'Rainy Day Fund'),
(25, '2023-01-15T10:00:00Z', false, 'Savings'),
(30, '2023-02-20T11:00:00Z', false, 'Checking');

Kişileri Hesaplara Bağlama

INSERT INTO PersonOwnAccount (id, account_id, create_time) VALUES
(1, 7, '2020-01-10T14:22:20.222Z'),
(2, 16, '2020-01-28T01:55:09.206Z'),
(3, 20, '2020-02-18T13:44:20.655Z'),
(4, 25, '2023-01-15T10:00:00Z'),
(5, 30, '2023-02-20T11:00:00Z');

Transfer ekleme

INSERT INTO AccountTransferAccount (id, to_id, amount, create_time, order_number) VALUES
(7, 16, 300, '2024-02-28T10:00:00Z', 'ORD123'),
(7, 16, 100, '2024-02-29T11:00:00Z', 'ORD124'),
(16, 20, 300, '2024-02-29T12:00:00Z', 'ORD125'),
(20, 7, 500, '2024-02-29T13:00:00Z', 'ORD126'),
(20, 16, 200, '2024-02-29T14:00:00Z', 'ORD127'),
(7, 25, 150.75, '2024-03-01T12:00:00Z', 'ORD456'),
(25, 30, 200.00, '2024-03-02T14:30:00Z', 'ORD457'),
(30, 16, 50.25, '2024-03-03T16:00:00Z', 'ORD458');

3. Gemini CLI ve Spanner MCP'yi yapılandırma

Bu laboratuvar, çoğu işlemi gerçekleştirmek için ana aracı olarak Gemini CLI'yı kullanacak şekilde tasarlanmıştır. İlk adım, Gemini CLI'yı uzak Spanner MCP sunucusuyla çalışacak şekilde yapılandırmaktır. Ayrıca, Gemini CLI'nin en yeni sürümünü ve Gemini-3-pro veya Gemini-3-flash (şu anda önizleme aşamasında) gibi Gemini'ın en yeni sürümünü kullanmanız önemle tavsiye edilir.

Gemini CLI'nın en yeni sürümüne zaten sahipseniz ve en yeni Gemini modellerini kullanacak şekilde yapılandırdıysanız sonraki 2 adımı atlayıp doğrudan 3. adıma geçebilirsiniz.

Gemini API anahtarı alma

Gemini CLI'nizde en yeni Gemini modellerini kullanmak için Gemini CLI'nin API anahtarı kimlik doğrulamasıyla yapılandırılması gerekir. API anahtarını Google AI Studio'dan veya

1. Tarayıcınızda Google AI Studio -> API anahtarı al'a gidin.
2. Ekranın sağ tarafında Create API key düğmesini tıklayın.
3. Pop-up pencerede projenizi seçin veya görünmüyorsa içe aktarın.

4. API anahtarını oluşturun.
5. Sağ taraftaki kopyalama düğmesini kullanarak anahtarı kopyalayabilirsiniz.

Anahtar hazırlanır ve artık Gemini CLI için kullanılabilir.

Gemini CLI'yı yapılandırma

Gemini KSA, ayarlar yapılandırma dosyası aracılığıyla veya /settings komutu kullanılarak etkileşimli olarak yapılandırılabilir. Ayarlarımızın, ayar dosyamızda korunmasını istiyoruz.

Öncelikle projemiz için bir dizin oluşturacağız. Dizine projectspannermcp adını verelim ve aşağıdaki komutları kullanarak bu dizine geçelim.

mkdir ~/projectspannermcp
cd ~/projectspannermcp

Dizinde, Gemini yapılandırma dosyaları için bir dizin oluşturup tüm komutlarımızı çalıştıracağız. Gemini CLI, varsayılan olarak bir kullanıcı kapsamı yapılandırma dosyası ve ~/.gemini dizinine yüklenen uzantıları kullanır. Ancak ~/projectspannermcp dizinimizde kendi proje kapsamı yapılandırmamızı oluşturacağız. Yapılandırma dizinini ve dosyalarını oluşturarak başlayalım.

mkdir ~/projectspannermcp/.gemini
touch ~/projectspannermcp/.gemini/settings.json

Ardından, Cloud Shell Düzenleyici'yi kullanarak ~/projectspannermcp/.gemini/settings.json dosyasını açıyoruz.

edit ~/projectspannermcp/.gemini/settings.json

Açılan düzenleyici penceresine aşağıdaki yapılandırmayı ekleyin.

{
  "general": {
    "preferredEditor": "vscode",
    "previewFeatures": true,
    "sessionRetention": {
      "enabled": true
    }
  },
  "ide": {
    "enabled": true,
    "hasSeenNudge": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  },
  "ui": {
    "theme": "Default"
  },
  "tools": {
    "shell": {
      "enableInteractiveShell": false
    }
  }
}

Dosyayı düzenledikten sonra değişikliklerinizi kaydetmek için ctrl+s simgesini kullanabilir ve Open Terminal düğmesini tıklayarak terminale geri dönebilirsiniz.

Yukarıdaki settings.json dosyası, Gemini CLI kimlik doğrulama türünüzü gemini-api-key olarak ayarlar ve modele anahtarı sağlamanız gerekir. Bunu, Gemini CLI ile çalışmak istediğiniz dizinde bir .env dosyası oluşturarak ve Gemini CLI kimlik doğrulaması için API anahtarınızı IDE'yi başlattığınızda alınacak bir ortam değişkeni olarak saklayarak yapabilirsiniz.

Cloud Shell Düzenleyici'yi kullanarak dosyayı düzenleyelim.

edit ~/projectspannermcp/.env

Ayrıca, yukarıdaki "Gemini API anahtarı edinme" adımında oluşturduğunuz API anahtarınızı saklayın.

GEMINI_API_KEY= <YOUR_API_KEY>

Artık terminale geri dönüp devam edebilirsiniz. Bir sonraki adım, Gemini CLI'nizi en yeni sürüme güncellemenizdir. Google Cloud Shell'deki veya ortamınızdaki sürüm eski olabilir ve en son yapılandırmalar ile MCP hizmetleriyle düzgün çalışmayabilir. Bu nedenle, Gemini CLI'yı en son sürüme güncellemeniz ve başlatmanız önemlidir. Terminalde aşağıdakileri çalıştırın.

cd ~/projectspannermcp/
npm install -g @google/gemini-cli@latest

Artık sürümü doğrulayabilirsiniz. Google Cloud Shell'de çalışıyorsanız kabuğu her yeniden başlattığınızda önceki sürüme dönebileceğini lütfen unutmayın. Gemini CLI'de yaptığınız değişiklikler Cloud Shell'de kalıcı olmaz.

gemini --version

En yeni Gemini CLI sürümü (laboratuvar yazılırken sürüm 0.27) gösterilmelidir. En yeni Gemini CLI sürümünü buradan doğrulayabilirsiniz. Şimdi de başlatıp en yeni Gemini modelini kullandığından emin olalım. Gemini CLI'yı başlatmak için proje klasörünüzde aşağıdaki komutu çalıştırın.

gemini

Gemini CLI başlatıldığında arayüzde /about komutunu çalıştırarak sürümü ve modeli kontrol edebilirsiniz. Aşağıdaki resme benzer bir sonuç alırsınız.

En yeni Gemini-3 modelinin kullanıldığını görebilirsiniz. Aşağıdaki adımlarda doğal dil sorgulama gösterilirken Gemini-3 modeli kullanılır.

Gemini CLI'ı Spanner MCP'yi kullanacak şekilde yapılandırma

settings.json dosyasına eklememiz gereken bir şey daha var. Öncelikle gemini cli'den çıkın (Ctrl+C tuşlarına iki kez basabilirsiniz).

Yukarıdakiyle aynı settings.json içinde, Spanner MCP sunucumuzu yapılandırmak için bit ekleyeceğiz. settings.json dosyasının tamamını aşağıda bulabilirsiniz. "mcpServers" ile başlayan kısma dikkat edin.

{
 "general": {
   "preferredEditor": "vscode",
   "previewFeatures": true,
   "sessionRetention": {
     "enabled": true
   }
 },
 "ide": {
   "enabled": true,
   "hasSeenNudge": true
 },
 "security": {
   "auth": {
     "selectedType": "gemini-api-key"
   }
 },
 "ui": {
   "theme": "Default"
 },
 "tools": {
   "shell": {
     "enableInteractiveShell": false
   }
 },
 "mcpServers": {
   "spanner": {
     "httpUrl": "https://spanner.googleapis.com/mcp",
     "authProviderType": "google_credentials",
     "oauth": {
       "scopes": ["https://www.googleapis.com/auth/spanner.admin",
                  "https://www.googleapis.com/auth/spanner.data"]
     },
     "timeout": 5000
   }
 },
 "mcp": {
   "allowed": [
     "spanner"
   ]
 }
}

Bir sonraki adıma geçmeden önce kimliğinizi doğrulayın.

gcloud auth application-default login

Kimlik doğrulama işleminden sonra gemini-cli'yi tekrar başlatın.

gemini

4. Grafik odaklı sorgular da dahil olmak üzere çok formatlı içerikler oluşturma

Yapılandırılmış projenizdeki Spanner örneklerini listeleyerek başlayalım.

"Lütfen <project1> projemdeki tüm Spanner örneklerini listeleyin (proje kimliğinizle değiştirin)"

Yanıt:

The Spanner instances in your project are:
 [instance1]

"Lütfen <instance1> (örneğinizle değiştirin) içindeki tüm veritabanlarını listeleyin."

Yanıt:

The Spanner databases in [instance1] are:
  [database1]

Ardından, Gemini'a Spanner kurulumu bölümünde DDL ifadelerini ve ekleme ifadelerini çalıştırdığınız örneği/veritabanını hatırlamasını söyleyelim:

"Aksi belirtilmediği sürece tüm sorguların <your-instance> örneğindeki <your-db> veritabanına gönderileceğini varsayın"

NOTE: Lütfen yukarıdaki DDL ifadelerini ve ekleme ifadelerini çalıştırdığınız örneği/veritabanını kullanın.

Bağlantı kurulduktan sonra Gemini modeli, grafik şemasını anlar. Artık doğal dili kullanarak karmaşık geçişler gerçekleştirebilirsiniz.

Model, bunları otomatik olarak GQL'ye (Grafik Sorgu Dili) çevirir:

Ağ Yapılarını Tanımlama

"FinGraph' mülk grafiğinin yapısını açıklayın. Düğüm ve kenar etiketleri nelerdir?"

Yanıt:

  Node Labels
   * `Account`: Represents financial accounts.
       * Properties: id, create_time, is_blocked, nick_name
   * `Person`: Represents individuals.
       * Properties: id, name, birthday, country, city

  Edge Labels
   * `Transfers`: Represents a transfer between two Account nodes.
       * Source: Account
       * Destination: Account
       * Properties: id, to_id, amount, create_time, order_number
   * `Owns`: Represents a Person owning an Account.
       * Source: Person
       * Destination: Account
       * Properties: id, account_id, create_time

Sahtekarlık ve Döngü Algılama

"A hesabından gönderilen ve 3 aktarım içinde A hesabına geri dönen tüm döngüsel transferleri bul."

Yanıt:

The analysis confirms the following circular transfers where money returns to the originating account within 3 hops:

  3-Hop Cycles
  Money travels through two intermediate accounts before returning to the origin.
   * Account 16 (Involved in multiple 3-hop paths)
   * Account 20 (Involved in multiple 3-hop paths)
   * Account 7 (Involved in multiple 3-hop paths)

These accounts are participating in circular flow patterns of varying lengths.

Derin İlişki Analizi

"Son 24 ayda farklı kişilere ait hesaplara 499 ABD dolarından fazla para gönderen hesapların sahiplerini belirle."

Yanıt:

Dana is the only person who owns an account that has sent more than $499 to an account owned by a different person in the last 24 months.

(Specifically, her account sent exactly $500, which is the maximum transfer amount in the database).

Yol bulma

"Hesap kimliği 16 ile hesap kimliği 20 arasındaki en kısa aktarım yolunu bul."

Yanıt:

The shortest path between Account 16 and Account 20 is 1 hop.

This means there is a direct transfer from Account 16 to Account 20.

5. Tebrikler!

Codelab'i tamamladığınız için tebrik ederiz.

İşlediğimiz konular

Bu codelab'de, gemini-cli'yi Spanner MCP sunucusuyla nasıl yapılandıracağınızı ve analizleri ortaya çıkarmak için Spanner Graph verilerinizde doğal dil sorguları yayınlamayı öğrendiniz. Önemli aşamaların özeti:

• Yönetilen altyapı: Uzak Spanner MCP sunucusu etkinleştirildi. Böylece yerel proxy'lere veya MCP araç kutusuna gerek kalmadı.
• Graph Integration: Karmaşık ilişkileri temsil etmek için Düğümler ve Kenarlar içeren bir Spanner Property Graph (FinGraph) yapılandırıldı.
• Yerel Araçlar: Standart bir URI şeması kullanarak Gemini CLI'yi doğrudan yönetilen Spanner uç noktasına bağladık.
• Doğal Dil SQL ve GQL: Sunucu, grafiğe özel istemlerle çalıştırıldı. Bu sayede LLM, manuel SQL/GQL kodlaması olmadan çok adımlı geçişler ve döngü algılama gerçekleştirebildi.
• Kurumsal kullanıma hazır olma: Yönetilen MCP'nin, yapay zeka aracıları için operasyonel verilerle etkileşim kurmak üzere nasıl ölçeklenebilir ve kimliği doğrulanmış bir yol sağladığı incelendi.