Codelab: serwer MCP Spanner

1. Przegląd

Ten przewodnik pokazuje, jak wysyłać zapytania do grafu w Spannerze za pomocą gemini-cli i serwerów Model Context Protocol (MCP) Google. Dzięki integracji bazy danych multimodelowej Spanner, w tym Spanner Graph, z zarządzaną usługą MCP możesz używać języka naturalnego do odkrywania ukrytych relacji w danych, takich jak kręgi oszustw czy zależności w łańcuchu dostaw, w jednej bazie danych bez ręcznego pisania złożonych zapytań w języku GQL (Graph Query Language) lub SQL.

Czego się nauczysz

Jak skonfigurować wielomodelową bazę danych Spanner, w tym Spanner Graph dla MCP.
Jak połączyć interfejs wiersza poleceń Gemini z zarządzanym zdalnym punktem końcowym usługi Spanner.
Jak używać języka naturalnego do automatycznego generowania kodu SQL zintegrowanego z GQL w celu wykonywania przechodzenia po grafie i dopasowywania wzorców wraz z operacjami relacyjnymi.
Sprawdzone metody zabezpieczania danych wykresu w przepływach pracy AI.

Wymagania wstępne

Projekt Google Cloud z włączonymi płatnościami.
Dostęp do terminala (np. Cloud Shell). Zobacz to ćwiczenie Codelab.
Interfejs gcloud CLI jest zainstalowany i uwierzytelniony.
Dostęp do interfejsu wiersza poleceń Gemini.

UWAGA: wszystkie polecenia uruchamiaj w terminalu systemu Unix. Aby uzyskać dostęp do terminala z gcloud i odpowiednim uwierzytelnianiem, zapoznaj się z wymaganiami wstępnymi powyżej.

2. Konfigurowanie środowiska Spanner Multi-model

Zarządzany MCP działa najlepiej, gdy schemat bazy danych jest wstępnie zdefiniowany. Na podstawie przykładów grafów Spannera utworzymy graf finansowy „Wykrywanie oszustw”.

Włącz interfejsy API

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}

Tworzenie schematu bazy danych

Utwórz instancję i bazę danych z tabelami bazy danych i grafem właściwości. Ten schemat śledzi konta, osoby i przelewy między nimi.

UWAGA: te instrukcje DDL możesz uruchomić w Spanner Studio. Informacje o tworzeniu bazy danych Spanner i wykonywaniu na niej zapytań w konsoli GCP znajdziesz pod tym linkiem.

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

Wypełnianie danych

Wstaw osoby

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

Wstawianie kont

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

Łączenie osób z kontami

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

Dodawanie transferów

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. Konfigurowanie interfejsu wiersza poleceń Gemini i MCP Spanner

W tym laboratorium interfejs wiersza poleceń Gemini jest głównym agentem wykonującym większość działań. Pierwszym krokiem jest skonfigurowanie go do pracy ze zdalnym serwerem Spanner MCP. Zalecamy też używanie najnowszej wersji interfejsu wiersza poleceń Gemini i najnowszej wersji Gemini, np. Gemini-3-pro lub Gemini-3-flash (obecnie w wersji podglądowej).

Jeśli masz już najnowszą wersję interfejsu wiersza poleceń Gemini i skonfigurowano ją do korzystania z najnowszych modeli Gemini, możesz pominąć 2 kolejne kroki i przejść bezpośrednio do kroku 3.

Pobieranie klucza interfejsu Gemini API

Aby korzystać z najnowszych modeli Gemini w interfejsie wiersza poleceń Gemini, musisz skonfigurować uwierzytelnianie za pomocą klucza interfejsu API. Klucz interfejsu API możemy uzyskać w Google AI Studio.

W przeglądarce otwórz Google AI Studio –> Uzyskaj klucz interfejsu API.
Po prawej stronie ekranu kliknij przycisk Create API key.
W wyskakującym okienku wybierz projekt lub zaimportuj go, jeśli nie jest widoczny.

Utwórz klucz interfejsu API.
Możesz skopiować klucz, klikając przycisk kopiowania po prawej stronie.

Klucz jest gotowy i możemy go teraz używać w interfejsie wiersza poleceń Gemini.

Konfigurowanie interfejsu wiersza poleceń Gemini

Interfejs Gemini CLI można skonfigurować za pomocą pliku konfiguracji ustawień lub interaktywnie za pomocą polecenia /settings. Chcemy, aby nasze ustawienia były zachowane w pliku ustawień.

Najpierw utworzymy katalog projektu. Nazwijmy katalog projectspannermcp i przejdźmy do niego za pomocą tych poleceń.

mkdir ~/projectspannermcp
cd ~/projectspannermcp

W tym katalogu utworzymy katalog plików konfiguracyjnych Gemini i będziemy uruchamiać wszystkie polecenia. Interfejs wiersza poleceń Gemini domyślnie używa pliku konfiguracji zakresu użytkownika i rozszerzeń zainstalowanych w katalogu ~/.gemini. Utworzymy jednak własną konfigurację zakresu projektu w katalogu ~/projectspannermcp. Zacznijmy od utworzenia katalogu i plików konfiguracyjnych.

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

Następnie otwieramy plik ~/projectspannermcp/.gemini/settings.json za pomocą edytora Cloud Shell.

edit ~/projectspannermcp/.gemini/settings.json

W otwartym oknie edytora dodaj tę konfigurację.

{
  "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
    }
  }
}

Po edycji pliku możesz użyć ctrl+s, aby zapisać zmiany, i wrócić do terminala, klikając przycisk Open Terminal.

W powyższym pliku settings.json typ uwierzytelniania interfejsu Gemini CLI jest ustawiony na gemini-api-key. Musisz podać klucz do modelu. Możesz to zrobić, tworząc plik .env w katalogu, w którym chcesz pracować z interfejsem wiersza poleceń Gemini, i przechowując klucz interfejsu API do uwierzytelniania interfejsu wiersza poleceń Gemini jako zmienną środowiskową, która zostanie pobrana po uruchomieniu środowiska IDE.

Edytowanie pliku za pomocą edytora Cloud Shell

edit ~/projectspannermcp/.env

i przechowuj klucz interfejsu API Gemini utworzony w kroku „Uzyskiwanie klucza interfejsu API Gemini” powyżej.

GEMINI_API_KEY= <YOUR_API_KEY>

Teraz możesz wrócić do terminala i kontynuować. Następnym krokiem jest zaktualizowanie interfejsu wiersza poleceń Gemini do najnowszej wersji. Wersja w Google Cloud Shell lub w Twoim środowisku może być nieaktualna i może nie działać prawidłowo z najnowszymi konfiguracjami i usługami MCP. Dlatego ważne jest, aby zaktualizować interfejs wiersza poleceń Gemini do najnowszej wersji i go uruchomić. W terminalu wykonaj te czynności.

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

Teraz możesz sprawdzić wersję. Pamiętaj, że jeśli pracujesz w Google Cloud Shell, za każdym razem, gdy ponownie uruchomisz powłokę, może ona wrócić do poprzedniej wersji. Zmiany wprowadzone w samym interfejsie wiersza poleceń Gemini nie są trwałe w Cloud Shell.

gemini --version

Powinna się wyświetlić najnowsza wersja interfejsu Gemini CLI (w momencie pisania tego laboratorium jest to wersja 0.27). Najnowszą wersję interfejsu wiersza poleceń Gemini możesz sprawdzić tutaj. Teraz możemy go uruchomić i sprawdzić, czy korzysta z najnowszego modelu Gemini. Aby uruchomić interfejs wiersza poleceń Gemini, w folderze projektu uruchom to polecenie:

gemini

Gdy interfejs wiersza poleceń Gemini zostanie uruchomiony, możesz sprawdzić wersję i model, uruchamiając w interfejsie polecenie /about. Powinien pojawić się obraz podobny do tego poniżej.

Widać, że korzysta z najnowszego modelu Gemini 3. Poniższe kroki, które pokazują zapytania w języku naturalnym, wymagają użycia modelu Gemini 3.

Konfigurowanie interfejsu wiersza poleceń Gemini do korzystania z platformy Spanner MCP

Do pliku settings.json musimy dodać jeszcze jedną rzecz. Najpierw zamknij interfejs Gemini CLI (możesz dwukrotnie nacisnąć Ctrl+C).

W tym samym settings.json co powyżej dodamy fragment kodu, który skonfiguruje nasz serwer MCP Spanner. Poniżej znajdziesz pełną wersję pliku settings.json. Zwróć uwagę na fragment zaczynający się od "mcpServers".

{
 "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"
   ]
 }
}

Zanim przejdziesz do następnego kroku, uwierzytelnij się.

gcloud auth application-default login

Po uwierzytelnieniu ponownie uruchom gemini-cli.

gemini

4. Generowanie zapytań dotyczących wielu modeli, w tym zapytań dotyczących grafów

Zacznijmy od wyświetlenia listy instancji Spanner w skonfigurowanym projekcie.

„Please list all Spanner instances in my project <project1 > (replace with your project id)” (Wyświetl wszystkie instancje Spannera w moim projekcie<project1> (zastąp identyfikatorem projektu)).

Odpowiedź:

The Spanner instances in your project are:
 [instance1]

„Wymień wszystkie bazy danych w <instance1> (zastąp nazwą swojej instancji)”.

Odpowiedź:

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

Następnie poinformujmy model Gemini, aby zapamiętał instancję lub bazę danych, w której zostały uruchomione instrukcje DDL i instrukcje wstawiania w sekcji konfiguracji Spannera:

„Zakładaj, że wszystkie zapytania mają być przesyłane do bazy danych <your-db> w instancji <your-instance>, o ile nie podano inaczej”.

NOTE użyj instancji lub bazy danych, w której zostały wykonane powyższe instrukcje DDL i instrukcje wstawiania.

Po połączeniu model Gemini rozpoznaje schemat wykresu. Teraz możesz przeprowadzać zaawansowane przeszukiwania za pomocą języka naturalnego.

Model będzie automatycznie tłumaczyć te elementy na język GQL (Graph Query Language):

Identyfikowanie struktur sieci

„Opisz strukturę wykresu właściwości „FinGraph”. Jakie są etykiety węzłów i krawędzi?

Odpowiedź:

  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

Wykrywanie oszustw i cykli

„Znajdź wszystkie transfery cykliczne, w których pieniądze zostały wysłane z konta A i ostatecznie wróciły na to konto w ciągu 3 kroków”.

Odpowiedź:

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.

Dogłębna analiza relacji

„Zidentyfikuj wszystkie osoby, które są właścicielami kont, z których w ciągu ostatnich 24 miesięcy wysłano na konta należące do innych osób środki o wartości ponad 499 USD”.

Odpowiedź:

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

Wyznaczanie ścieżki

„Znajdź najkrótszą ścieżkę przelewów między kontem o identyfikatorze 16 a kontem o identyfikatorze 20”.

Odpowiedź:

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. Gratulacje!

Gratulujemy ukończenia ćwiczenia.

Omówione zagadnienia

W tym samouczku dowiedzieliśmy się, jak skonfigurować gemini-cli z serwerem Spanner MCP i wysyłać zapytania w języku naturalnym do danych Spanner Graph, aby uzyskać statystyki. Oto podsumowanie najważniejszych wydarzeń:

Zarządzana infrastruktura: włączono zdalny serwer MCP Spanner, co eliminuje potrzebę korzystania z lokalnych serwerów proxy lub zestawu narzędzi MCP.
Integracja z wykresem: skonfigurowano wykres właściwości Spanner (FinGraph) z węzłami i krawędziami, aby przedstawić złożone relacje.
Narzędzia natywne: interfejs wiersza poleceń Gemini został połączony bezpośrednio z zarządzanym punktem końcowym Spanner za pomocą standardowego schematu URI.
SQL i GQL w języku naturalnym: przetestowano serwer za pomocą promptów dotyczących grafu, co umożliwiło LLM wykonywanie wieloetapowych przejść i wykrywanie cykli bez ręcznego kodowania w SQL lub GQL.
Gotowość do zastosowań korporacyjnych: omówiliśmy, jak zarządzana platforma MCP zapewnia skalowalną, uwierzytelnioną ścieżkę interakcji agentów AI z danymi operacyjnymi.