Atelier de programmation : serveur MCP Spanner

1. Présentation

Cet atelier de programmation explique comment exécuter des requêtes graphiques sur Spanner à l'aide de gemini-cli et des serveurs MCP (Model Context Protocol) de Google. En intégrant la base de données multimode de Spanner, y compris Spanner Graph, au service MCP géré, vous pouvez utiliser le langage naturel pour découvrir les relations cachées dans vos données (cercles de fraude ou dépendances de la chaîne d'approvisionnement, par exemple) dans une seule base de données, sans avoir à écrire manuellement des requêtes GQL (Graph Query Language) ou SQL complexes.

Objectifs de l'atelier

Découvrez comment configurer une base de données Spanner multimode, y compris Spanner Graph pour MCP.
Comment connecter la Gemini CLI à un point de terminaison de service Spanner distant géré.
Utiliser le langage naturel pour générer du code SQL intégré à GQL afin d'effectuer automatiquement des traversées de graphe et des correspondances de motifs, ainsi que des opérations relationnelles.
Bonnes pratiques pour sécuriser les données graphiques dans les workflows d'IA.

Prérequis

Projet Google Cloud avec facturation activée
Accès à un terminal (comme Cloud Shell). Consultez cet atelier de programmation.
La CLI gcloud doit être installée et authentifiée.
Accès à la CLI Gemini.

REMARQUE : Vous allez exécuter toutes les commandes dans un terminal Unix. Veuillez consulter les prérequis ci-dessus pour accéder à un terminal avec accès à gcloud et à une authentification appropriée.

2. Configurer l'environnement multimode Spanner

Le MCP géré fonctionne mieux lorsque le schéma de la base de données est prédéfini. Nous allons créer un graphique de "détection des fraudes" financières basé sur les exemples de graphiques Spanner.

Activer les 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}

Créer le schéma de base de données

Créez une instance et une base de données avec des tables de base de données et un graphique de propriétés. Ce schéma permet de suivre les comptes, les personnes et les transferts entre eux.

REMARQUE : Vous pouvez exécuter ces instructions LDD à partir de Spanner Studio. Pour savoir comment créer une base de données Spanner et l'interroger depuis la console GCP, veuillez consulter ce lien.

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

Renseigner les données

Insérer des personnes

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

Insérer des comptes

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

Associer des personnes à des comptes

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

Ajouter des transferts

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. Configurer Gemini CLI et Spanner MCP

Cet atelier est conçu pour utiliser Gemini CLI comme agent principal pour effectuer la plupart des actions. La première étape consiste à le configurer pour qu'il fonctionne avec le serveur MCP Spanner distant. Il est également fortement recommandé d'utiliser la dernière version de Gemini CLI et la dernière version de Gemini, comme Gemini-3-pro ou Gemini-3-flash (actuellement en aperçu).

Si vous disposez déjà de la dernière version de Gemini CLI et que vous l'avez configurée pour utiliser les derniers modèles Gemini, vous pouvez ignorer les deux prochaines étapes et passer directement à l'étape 3.

Obtenir une clé API Gemini

Pour utiliser les derniers modèles Gemini dans votre Gemini CLI, vous devez la configurer avec une authentification par clé API. Nous pouvons obtenir la clé API dans Google AI Studio.

Accédez à Google AI Studio > Obtenir une clé API dans votre navigateur.
Sur le côté droit de l'écran, cliquez sur le bouton Create API key.
Dans la fenêtre pop-up, sélectionnez votre projet ou importez-le s'il n'est pas visible.

Créez la clé API.
Vous pouvez copier la clé à l'aide du bouton de copie situé sur la droite.

La clé est préparée et nous pouvons maintenant l'utiliser pour Gemini CLI.

Configurer Gemini CLI

Vous pouvez configurer Gemini CLI à l'aide du fichier de configuration des paramètres ou de manière interactive à l'aide de la commande /settings. Nous voulons que nos paramètres soient conservés dans notre fichier de paramètres.

Nous allons d'abord créer un répertoire pour notre projet. Appelons le répertoire projectspannermcp et passons à ce répertoire à l'aide des commandes suivantes.

mkdir ~/projectspannermcp
cd ~/projectspannermcp

Dans le répertoire que nous allons créer, nous allons créer un répertoire pour les fichiers de configuration Gemini et exécuter toutes nos commandes. Par défaut, Gemini CLI utilise un fichier de configuration de portée utilisateur et des extensions installées dans le répertoire ~/.gemini. Toutefois, nous allons créer notre propre configuration de champ d'application du projet dans notre répertoire ~/projectspannermcp. Commençons par créer le répertoire et les fichiers de configuration.

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

Ouvrez ensuite le fichier ~/projectspannermcp/.gemini/settings.json à l'aide de l'éditeur Cloud Shell.

edit ~/projectspannermcp/.gemini/settings.json

Dans la fenêtre de l'éditeur qui s'ouvre, ajoutez la configuration suivante.

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

Après avoir modifié le fichier, vous pouvez utiliser ctrl+s pour enregistrer vos modifications et revenir au terminal en cliquant sur le bouton Open Terminal.

Le fichier settings.json ci-dessus définit votre type d'authentification Gemini CLI sur "gemini-api-key". Vous devez fournir la clé au modèle. Pour ce faire, créez un fichier .env dans le répertoire avec lequel vous souhaitez utiliser Gemini CLI, puis stockez votre clé API pour l'authentification Gemini CLI en tant que variable d'environnement. Elle sera récupérée lorsque vous démarrerez l'IDE.

Modifions le fichier à l'aide de l'éditeur Cloud Shell.

edit ~/projectspannermcp/.env

Stockez la clé API Gemini créée à l'étape "Obtenir une clé API Gemini" ci-dessus.

GEMINI_API_KEY= <YOUR_API_KEY>

Vous pouvez maintenant revenir au terminal et continuer. L'étape suivante consiste à mettre à jour votre Gemini CLI vers la dernière version. La version dans Google Cloud Shell ou dans votre environnement peut être obsolète et ne pas fonctionner correctement avec les dernières configurations et les services MCP. Il est donc important de mettre à jour Gemini CLI vers la dernière version et de le démarrer. Dans le terminal, exécutez la commande suivante.

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

Vous pouvez maintenant vérifier la version. Veuillez noter que si vous travaillez dans Google Cloud Shell, il est possible que le shell revienne à la version précédente chaque fois que vous le redémarrez. Les modifications que vous apportez à Gemini CLI elle-même ne sont pas permanentes dans Cloud Shell.

gemini --version

La dernière version de Gemini CLI devrait s'afficher (version 0.27 au moment de la rédaction de l'atelier). Pour vérifier la dernière version de Gemini CLI, cliquez ici. Nous pouvons maintenant le démarrer et nous assurer qu'il utilise le dernier modèle Gemini. Exécutez la commande suivante dans le dossier de votre projet pour démarrer Gemini CLI.

gemini

Lorsque Gemini CLI démarre, vous pouvez vérifier la version et le modèle en exécutant la commande /about dans l'interface. Vous devriez obtenir un résultat semblable à l'image ci-dessous.

Vous pouvez voir qu'il utilise le dernier modèle Gemini-3. Les étapes ci-dessous qui illustrent les requêtes en langage naturel nécessitent l'utilisation du modèle Gemini-3.

Configurer Gemini CLI pour utiliser Spanner MCP

Il reste une chose à ajouter au fichier settings.json. Tout d'abord, quittez Gemini CLI (vous pouvez appuyer deux fois sur Ctrl+C).

Dans le même settings.json que ci-dessus, nous allons ajouter le bit pour configurer notre serveur MCP Spanner. Vous trouverez ci-dessous le fichier settings.json complet. Notez la partie qui commence par "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"
   ]
 }
}

Avant de passer à l'étape suivante, authentifiez-vous.

gcloud auth application-default login

Après l'authentification, redémarrez gemini-cli.

gemini

4. Générer des requêtes multimodèles, y compris axées sur les graphiques

Commençons par lister les instances Spanner dans votre projet configuré.

"Veuillez lister toutes les instances Spanner de mon projet <project1> (remplacez par l'ID de votre projet)"

Response:

The Spanner instances in your project are:
 [instance1]

"Veuillez lister toutes les bases de données dans <instance1> (remplacez par votre instance)"

Response:

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

Ensuite, demandons à Gemini de se souvenir de l'instance/base de données dans laquelle vous avez exécuté les instructions DDL et les instructions d'insertion dans la section de configuration de Spanner :

"Sauf indication contraire, supposez que toutes les requêtes doivent être envoyées à la base de données <your-db> dans l'instance <your-instance>."

NOTE : Veuillez utiliser l'instance/la base de données sur laquelle vous avez exécuté les instructions LDD et les instructions d'insertion ci-dessus.

Une fois connecté, le modèle Gemini comprend le schéma du graphique. Vous pouvez désormais exécuter des traversées sophistiquées en langage naturel.

Le modèle traduira automatiquement les éléments suivants en GQL (Graph Query Language) :

Identifier les structures de réseau

"Décris la structure du graphique de propriété "FinGraph". Quelles sont les étiquettes de nœuds et d'arêtes ?"

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

Détection des fraudes et des cycles

"Trouve tous les transferts circulaires où de l'argent a été envoyé depuis le compte A et finalement renvoyé au compte A en trois étapes."

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.

Analyse approfondie des relations

"Identifie toutes les personnes qui possèdent des comptes ayant envoyé plus de 499 $à des comptes appartenant à d'autres personnes au cours des 24 derniers mois."

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

Recherche de chemin

"Trouve le chemin de transfert le plus court entre le compte 16 et le compte 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. Félicitations !

Bravo ! Vous avez terminé cet atelier de programmation.

Points abordés

Dans cet atelier de programmation, vous avez appris à configurer gemini-cli avec le serveur MCP Spanner et à envoyer des requêtes en langage naturel sur vos données Spanner Graph pour obtenir des insights. Voici un récapitulatif des étapes clés :

Infrastructure gérée : le serveur MCP Spanner distant a été activé, ce qui élimine le besoin de proxys locaux ou de la boîte à outils MCP.
Intégration de graphiques : configuration d'un graphique de propriétés Spanner (FinGraph) avec des nœuds et des arêtes pour représenter des relations complexes.
Outils natifs : la CLI Gemini a été connectée directement au point de terminaison Spanner géré à l'aide d'un schéma d'URI standard.
SQL et GQL en langage naturel : le serveur a été testé avec des requêtes spécifiques aux graphiques, ce qui a permis au LLM d'effectuer des traversées multihops et de détecter les cycles sans codage manuel en SQL/GQL.
Adaptation aux entreprises : nous avons exploré comment le MCP géré fournit un chemin d'accès évolutif et authentifié permettant aux agents d'IA d'interagir avec les données opérationnelles.