Codelab: Spanner MCP-Server

1. Übersicht

In diesem Codelab wird gezeigt, wie Sie mit der gemini-cli und den MCP-Servern (Model Context Protocol) von Google Diagrammanfragen an Spanner senden. Durch die Integration der Multimodell-Datenbank von Spanner, einschließlich Spanner Graph, in den verwalteten MCP-Dienst können Sie mithilfe natürlicher Sprache verborgene Beziehungen in Ihren Daten aufdecken, z. B. Betrugsringe oder Abhängigkeiten in der Lieferkette, und zwar in einer einzigen Datenbank, ohne komplexe GQL- (Graph Query Language) oder SQL-Abfragen manuell schreiben zu müssen.

Lerninhalte

Einrichten einer Spanner-Multimodell-Datenbank einschließlich Spanner Graph für MCP
So stellen Sie eine Verbindung zwischen der Gemini CLI und einem verwalteten Remote-Spanner-Dienstendpunkt her.
So generieren Sie automatisch SQL, das in GQL integriert ist, um Graphdurchläufe und Mustervergleiche zusammen mit relationalen Operationen durchzuführen.
Best Practices zum Sichern von Diagrammdaten in KI-Workflows.

Vorbereitung

Google Cloud-Projekt mit aktivierter Abrechnungsfunktion
Zugriff auf ein Terminal (z. B. Cloud Shell) Dieses Codelab ansehen
Die gcloud-Befehlszeile ist installiert und authentifiziert.
Zugriff auf die Gemini CLI.

HINWEIS: Sie führen alle Befehle in einem Unix-Terminal aus. Die Voraussetzungen für den Zugriff auf ein Terminal mit Zugriff auf gcloud mit der richtigen Authentifizierung finden Sie oben.

2. Spanner Multi-model-Umgebung einrichten

Die verwaltete MCP funktioniert am besten, wenn das Datenbankschema vordefiniert ist. Wir erstellen einen Finanzgraphen zur Betrugserkennung auf Grundlage der Spanner Graph-Beispiele.

APIs aktivieren

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}

Datenbankschema erstellen

Instanz und Datenbank mit Datenbanktabellen und einem Property Graph erstellen In diesem Schema werden Konten, Personen und die Übertragungen zwischen ihnen erfasst.

HINWEIS: Sie können diese DDL-Anweisungen über Spanner Studio ausführen. Hier finden Sie Informationen zum Erstellen und Abfragen einer Spanner-Datenbank über die GCP Console.

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

Daten einfügen

Personen einfügen

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

Konten einfügen

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

Personen mit Konten verknüpfen

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

Übertragungen hinzufügen

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 und Spanner MCP konfigurieren

In diesem Lab wird die Gemini CLI als Haupt-Agent verwendet, um die meisten Aktionen auszuführen. Der erste Schritt besteht darin, sie für die Verwendung mit dem Remote-Spanner-MCP-Server zu konfigurieren. Außerdem wird dringend empfohlen, die aktuelle Version der Gemini CLI und die aktuelle Version von Gemini wie Gemini-3-pro oder Gemini-3-flash (derzeit als Vorabversion) zu verwenden.

Wenn Sie bereits die aktuelle Version der Gemini CLI haben und sie für die Verwendung der neuesten Gemini-Modelle konfiguriert haben, können Sie die nächsten beiden Schritte überspringen und direkt zu Schritt 3 gehen.

Gemini API-Schlüssel abrufen

Wenn Sie die neuesten Gemini-Modelle in Ihrer Gemini CLI verwenden möchten, muss sie mit der API-Schlüsselauthentifizierung konfiguriert sein. Wir können den API-Schlüssel entweder in Google AI Studio

Rufen Sie in Ihrem Browser Google AI Studio -> API-Schlüssel abrufen auf.
Klicken Sie rechts auf dem Bildschirm auf die Schaltfläche Create API key.
Wählen Sie im Pop-up-Fenster Ihr Projekt aus oder importieren Sie es, falls es dort nicht angezeigt wird.

Erstellen Sie den API-Schlüssel.
Sie können den Schlüssel mit der Schaltfläche „Kopieren“ auf der rechten Seite kopieren.

Der Schlüssel ist vorbereitet und kann jetzt für die Gemini CLI verwendet werden.

Gemini CLI konfigurieren

Die Gemini CLI kann über die Datei mit den Einstellungen oder interaktiv mit dem Befehl /settings konfiguriert werden. Wir möchten, dass unsere Einstellungen in unserer Einstellungsdatei beibehalten werden.

Zuerst erstellen wir ein Verzeichnis für unser Projekt. Nennen wir das Verzeichnis projectspannermcp und wechseln wir mit den folgenden Befehlen in dieses Verzeichnis.

mkdir ~/projectspannermcp
cd ~/projectspannermcp

In diesem Verzeichnis erstellen wir ein Verzeichnis für Gemini-Konfigurationsdateien und führen alle unsere Befehle aus. Standardmäßig verwendet die Gemini CLI eine Konfigurationsdatei für Nutzerbereiche und Erweiterungen, die im Verzeichnis „~/.gemini“ installiert sind. Wir erstellen jedoch eine eigene Projektbereichskonfiguration in unserem Verzeichnis „~/projectspannermcp“. Zuerst erstellen wir das Konfigurationsverzeichnis und die Konfigurationsdateien.

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

Öffnen Sie dann die Datei ~/projectspannermcp/.gemini/settings.json mit dem Cloud Shell-Editor.

edit ~/projectspannermcp/.gemini/settings.json

Fügen Sie im geöffneten Editorfenster die folgende Konfiguration hinzu.

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

Nachdem Sie die Datei bearbeitet haben, können Sie ctrl+s verwenden, um Ihre Änderungen zu speichern und zum Terminal zurückzukehren. Klicken Sie dazu auf die Schaltfläche Open Terminal.

In der oben genannten Datei „settings.json“ wird der Authentifizierungstyp für die Gemini CLI auf „gemini-api-key“ festgelegt. Sie müssen den Schlüssel für das Modell angeben. Dazu erstellen Sie eine .env-Datei in dem Verzeichnis, in dem Sie mit der Gemini CLI arbeiten möchten, und speichern Ihren API-Schlüssel für die Gemini CLI-Authentifizierung als Umgebungsvariable. Diese wird beim Start der IDE übernommen.

Datei mit dem Cloud Shell-Editor bearbeiten

edit ~/projectspannermcp/.env

Speichern Sie den API-Schlüssel, den Sie im Schritt „Gemini API-Schlüssel abrufen“ oben erstellt haben.

GEMINI_API_KEY= <YOUR_API_KEY>

Sie können jetzt zum Terminal zurückkehren und fortfahren. Im nächsten Schritt aktualisieren Sie Ihre Gemini CLI auf die neueste Version. Die Version in Google Cloud Shell oder in Ihrer Umgebung kann veraltet sein und funktioniert möglicherweise nicht richtig mit den neuesten Konfigurationen und MCP-Diensten. Es ist daher wichtig, dass Sie die Gemini CLI auf die neueste Version aktualisieren und starten. Führen Sie im Terminal Folgendes aus.

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

Jetzt können Sie die Version überprüfen. Wenn Sie in Google Cloud Shell arbeiten, wird bei jedem Neustart der Shell möglicherweise die vorherige Version wiederhergestellt. Die Änderungen, die Sie an der Gemini CLI selbst vornehmen, sind in Cloud Shell nicht dauerhaft.

gemini --version

Dort sollte die aktuelle Version der Gemini CLI angezeigt werden (Version 0.27 zum Zeitpunkt der Erstellung dieses Labs). Die aktuelle Version der Gemini CLI finden Sie hier. Jetzt können wir es starten und darauf achten, dass das neueste Gemini-Modell verwendet wird. Führen Sie den folgenden Befehl in Ihrem Projektordner aus, um die Gemini CLI zu starten.

gemini

Wenn die Gemini CLI gestartet wird, können Sie die Version und das Modell mit dem Befehl /about in der Benutzeroberfläche prüfen. Die Ausgabe sollte in etwa so aussehen:

Sie sehen, dass das neueste Gemini 3-Modell verwendet wird. Für die Schritte unten, in denen Abfragen in natürlicher Sprache demonstriert werden, ist das Gemini-3-Modell erforderlich.

Gemini CLI für die Verwendung von Spanner MCP konfigurieren

Wir müssen der Datei settings.json noch etwas hinzufügen. Beenden Sie zuerst die Gemini CLI (Sie können zweimal Strg + C drücken).

Im selben settings.json wie oben fügen wir den Bit hinzu, um unseren Spanner-MCP-Server zu konfigurieren. Die vollständige Datei „settings.json“ finden Sie unten. Achten Sie auf den Bit, der mit "mcpServers" beginnt.

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

Authentifizieren Sie sich, bevor Sie mit dem nächsten Schritt fortfahren.

gcloud auth application-default login

Starten Sie gemini-cli nach der Authentifizierung noch einmal.

gemini

4. Multi-Modell mit graphorientierten Anfragen generieren

Lassen Sie uns zuerst die Spanner-Instanzen in Ihrem konfigurierten Projekt auflisten.

„Bitte liste alle Spanner-Instanzen in meinem Projekt <project1 > auf.“ (Ersetzen Sie<project1> durch Ihre Projekt-ID.)

Response:

The Spanner instances in your project are:
 [instance1]

„Bitte liste alle Datenbanken in <instance1> auf (durch Ihre Instanz ersetzen).“

Response:

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

Als Nächstes müssen wir Gemini mitteilen, an welche Instanz/Datenbank Sie die DDL-Anweisungen und die Einfügeanweisungen im Abschnitt zur Spanner-Einrichtung gesendet haben:

„Gehen Sie davon aus, dass alle Anfragen für die Datenbank <your-db> in der Instanz <your-instance> eingereicht werden, sofern nicht anders angegeben.“

NOTE: Verwenden Sie die Instanz/Datenbank, für die Sie die DDL-Anweisungen und die Einfügeanweisungen oben ausgeführt haben.

Sobald die Verbindung hergestellt ist, kann das Gemini-Modell das Diagrammschema verstehen. Sie können jetzt komplexe Traversierungen in natürlicher Sprache ausführen.

Das Modell übersetzt diese automatisch in GQL (Graph Query Language):

Netzwerkstrukturen identifizieren

„Beschreibe die Struktur der Attributgrafik ‚FinGraph‘. Was sind die Knoten- und Kantenlabels?“

Response:

  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

Betrugs- und Zykluserkennung

„Finde alle zirkulären Überweisungen, bei denen Geld von Konto A gesendet und innerhalb von drei Schritten an Konto A zurückgegeben wurde.“

Response:

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.

Detaillierte Analyse von Beziehungen

„Identifiziere alle Personen, die Konten besitzen, über die in den letzten 24 Monaten mehr als 499 $an Konten gesendet wurden, die anderen Personen gehören.“

Response:

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

Pfadfindung

„Finde den kürzesten Pfad von Übertragungen zwischen Konto-ID 16 und Konto-ID 20.“

Response:

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. Glückwunsch!

Herzlichen Glückwunsch zum Abschluss des Codelabs.

Behandelte Themen

In diesem Codelab haben Sie gelernt, wie Sie die Gemini CLI mit dem Spanner MCP-Server konfigurieren und Abfragen in natürlicher Sprache für Ihre Spanner Graph-Daten ausführen, um Erkenntnisse zu gewinnen. Hier eine Zusammenfassung der wichtigsten Meilensteine:

Verwaltete Infrastruktur:Der Remote-Spanner-MCP-Server wurde aktiviert, sodass keine lokalen Proxys oder die MCP Toolbox mehr erforderlich sind.
Graph-Integration:Ein Spanner Property Graph (FinGraph) mit Knoten und Kanten wurde konfiguriert, um komplexe Beziehungen darzustellen.
Native Tools:Die Gemini CLI wurde über ein Standard-URI-Schema direkt mit dem verwalteten Spanner-Endpunkt verbunden.
SQL und GQL in natürlicher Sprache:Der Server wurde mit grafischen Prompts getestet, sodass das LLM Multi-Hop-Traversierungen und Zykluserkennung ohne manuelle SQL-/GQL-Programmierung durchführen konnte.
Unternehmensbereitschaft:Es wurde untersucht, wie der verwaltete MCP einen skalierbaren, authentifizierten Pfad für die Interaktion von KI-Agenten mit Betriebsdaten bietet.