Codelab: שרת MCP של Spanner

1. סקירה כללית

ב-codelab הזה מוסבר איך להנפיק שאילתות גרף ב-Spanner באמצעות gemini-cli ושרתי Model Context Protocol (‏MCP) של Google. שילוב של מסד נתונים מרובה-מודלים של Spanner, כולל Spanner Graph, עם שירות MCP מנוהל, מאפשר לכם להשתמש בשפה טבעית כדי לחשוף קשרים נסתרים בנתונים שלכם – כמו מעגלי הונאה או תלות בשרשרת האספקה – במסד נתונים יחיד, בלי לכתוב שאילתות מורכבות ב-GQL (Graph Query Language) או ב-SQL באופן ידני.

מה תלמדו

איך מגדירים מסד נתונים מרובה-מודלים של Spanner, כולל Spanner Graph, ל-MCP.
איך מחברים את Gemini CLI לנקודת קצה של שירות Spanner מרוחק מנוהל.
איך להשתמש בשפה טבעית כדי ליצור SQL שמשולב עם GQL באופן אוטומטי, כדי לבצע מעברים בגרף והתאמת תבניות, וגם פעולות יחסיות.
שיטות מומלצות לאבטחת נתונים גרפיים בתהליכי עבודה של AI.

דרישות מוקדמות

פרויקט ב-Google Cloud עם חיוב מופעל.
גישה לטרמינל (כמו Cloud Shell). מומלץ לעיין ב-Codelab הזה.
ה-CLI של gcloud מותקן ומאומת.
גישה ל-Gemini CLI.

הערה: כל הפקודות יופעלו בטרמינל של Unix. כדי לקבל גישה למסוף עם גישה ל-gcloud עם אימות מתאים, צריך לעמוד בדרישות המוקדמות שצוינו למעלה.

2. הגדרת סביבת ריבוי מודלים ב-Spanner

השיטה Managed MCP מתאימה במיוחד כשסכימת מסד הנתונים מוגדרת מראש. ניצור גרף פיננסי של 'זיהוי הונאות' על סמך הדוגמאות של Spanner Graph.

הפעלת ממשקי 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}

יצירת סכימת מסד הנתונים

יצירת מכונה ומסד נתונים עם טבלאות של מסד נתונים וגרף נכסים. הסכימה הזו עוקבת אחרי חשבונות, אנשים והעברות ביניהם.

הערה: אפשר להריץ את הצהרות ה-DDL האלה מ-Spanner Studio. בקישור הזה מפורט מידע על יצירה של מסד נתונים ב-Spanner ושליחת שאילתות לגביו דרך קונסולת GCP.

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

אכלוס נתונים

הוספת אנשים

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

הוספת חשבונות

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

קישור אנשים לחשבונות

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

הוספת העברות

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 ו-Spanner MCP

המעבדה מיועדת לשימוש ב-Gemini CLI כסוכן הראשי לביצוע רוב הפעולות, והשלב הראשון הוא להגדיר אותו לעבודה עם שרת Spanner MCP מרוחק. מומלץ מאוד להשתמש בגרסה העדכנית של Gemini CLI ובגרסה העדכנית של Gemini, כמו Gemini-3-pro או Gemini-3-flash (שנמצאות כרגע בגרסת טרום-השקה).

אם כבר יש לכם את הגרסה העדכנית של Gemini CLI והגדרתם אותה לשימוש במודלים העדכניים של Gemini, אתם יכולים לדלג על 2 השלבים הבאים ולעבור ישירות לשלב 3.

קבלת מפתח Gemini API

כדי להשתמש במודלים העדכניים של Gemini ב-Gemini CLI, צריך להגדיר אימות באמצעות מפתח API. אפשר לקבל את מפתח ה-API ב-Google AI Studio

בדפדפן, עוברים אל Google AI Studio -> Get API key.
בצד שמאל של המסך, לוחצים על הלחצן Create API key.
בחלון הקופץ בוחרים את הפרויקט או מייבאים אותו אם הוא לא מופיע שם.

יוצרים את מפתח ה-API.
אפשר להעתיק את המפתח באמצעות לחצן ההעתקה בצד שמאל.

המפתח מוכן ועכשיו אפשר להשתמש בו ב-Gemini CLI

הגדרת Gemini CLI

אפשר להגדיר את Gemini CLI באמצעות קובץ הגדרות או באופן אינטראקטיבי באמצעות הפקודה /settings. אנחנו רוצים שההגדרות שלנו יישמרו בקובץ ההגדרות.

קודם ניצור ספריה לפרויקט. נקרא לספרייה projectspannermcp ונעבור לספרייה הזו באמצעות הפקודות הבאות.

mkdir ~/projectspannermcp
cd ~/projectspannermcp

בספרייה ניצור ספרייה לקובצי ההגדרות של Gemini ונריץ את כל הפקודות שלנו. כברירת מחדל, Gemini CLI משתמש בקובץ תצורה של היקף משתמש ותוספים שמותקנים בספרייה ‎~/.gemini. אבל אנחנו ניצור הגדרה משלנו של היקף הפרויקט בספרייה ‎~/projectspannermcp. נתחיל ביצירת תיקיית ההגדרות והקבצים.

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

לאחר מכן פותחים את הקובץ ~/projectspannermcp/.gemini/settings.json באמצעות Cloud Shell Editor.

edit ~/projectspannermcp/.gemini/settings.json

בחלון העורך שנפתח, מוסיפים את ההגדרה הבאה.

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

אחרי עריכת הקובץ, אפשר להשתמש ב-ctrl+s כדי לשמור את השינויים ולחזור למסוף בלחיצה על הלחצן Open Terminal.

בקובץ settings.json שלמעלה, סוג האימות של Gemini CLI מוגדר כ-gemini-api-key, ואתם צריכים לספק את המפתח למודל. כדי לעשות את זה, יוצרים קובץ ‎ .env בספרייה שרוצים לעבוד איתה ב-Gemini CLI, ושומרים את מפתח ה-API לאימות ב-Gemini CLI כמשתנה סביבה שייקלט כשמפעילים את ה-IDE.

עריכת הקובץ באמצעות Cloud Shell Editor

edit ~/projectspannermcp/.env

מאחסנים את מפתח ה-API שנוצר בשלב 'קבלת מפתח Gemini API' שלמעלה.

GEMINI_API_KEY= <YOUR_API_KEY>

עכשיו אפשר לחזור למסוף ולהמשיך. בשלב הבא צריך לעדכן את Gemini CLI לגרסה העדכנית. יכול להיות שהגרסה ב-Google Cloud Shell או בסביבה שלכם תהיה מיושנת, ולא תפעל בצורה תקינה עם ההגדרות העדכניות ועם שירותי ה-MCP. לכן חשוב לעדכן את Gemini CLI לגרסה האחרונה ולהפעיל אותו. מריצים את הפקודה הבאה במסוף.

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

עכשיו אפשר לאמת את הגרסה. חשוב לזכור שאם אתם עובדים ב-Google Cloud Shell, יכול להיות שבכל פעם שתפעילו מחדש את ה-Shell הוא יחזור לגרסה הקודמת. השינויים שאתם מבצעים ב-Gemini CLI עצמו לא קבועים ב-Cloud Shell.

gemini --version

צריכה להופיע הגרסה העדכנית של Gemini CLI (גרסה 0.27 בזמן כתיבת המעבדה). כאן אפשר לבדוק מהי הגרסה העדכנית של Gemini CLI. עכשיו אפשר להפעיל אותו ולוודא שהוא משתמש במודל Gemini העדכני ביותר. מריצים את הפקודה הבאה בתיקיית הפרויקט כדי להפעיל את Gemini CLI.

gemini

כשמפעילים את Gemini CLI, אפשר לבדוק את הגרסה ואת המודל על ידי הרצת הפקודה /about בממשק. התוצאה אמורה להיות דומה לתמונה שלמטה.

אפשר לראות שהוא משתמש במודל Gemini-3 העדכני ביותר. השלבים הבאים שמדגימים שאילתות בשפה טבעית דורשים שימוש במודל Gemini-3.

הגדרת Gemini CLI לשימוש ב-Spanner MCP

יש עוד דבר אחד שצריך להוסיף לקובץ settings.json. קודם כל, יוצאים מ-Gemini CLI (אפשר ללחוץ פעמיים על Ctrl+C).

באותו קובץ settings.json שמופיע למעלה, נוסיף את החלק להגדרת שרת ה-MCP של Spanner. בהמשך מופיע הקובץ המלא settings.json. שימו לב לחלק שמתחיל ב-"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"
   ]
 }
}

לפני שממשיכים לשלב הבא, צריך לבצע אימות

gcloud auth application-default login

אחרי האימות, מפעילים מחדש את gemini-cli

gemini

4. יצירת מודל משולב, כולל שאילתות שמתמקדות בתרשימים

נתחיל בהצגת רשימה של מופעי Spanner בפרויקט שהגדרתם.

‫"Please list all Spanner instances in my project <project1> (replace with your project id)‎"

תשובה:

The Spanner instances in your project are:
 [instance1]

‫"Please list all databases in <instance1> (replace with your instance)"

תשובה:

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

בשלב הבא, נבקש מ-Gemini לזכור את המופע או מסד הנתונים שבהם הפעלתם את הצהרות ה-DDL ואת הצהרות ה-INSERT בקטע ההגדרה של Spanner:

"הנח שכל השאילתות יוגשו מול מסד הנתונים [your-db] במופע [your-instance] אלא אם צוין אחרת"

NOTE: חשוב להשתמש במופע או במסד הנתונים שעליהם הפעלתם את הצהרות ה-DDL ואת הצהרות ה-INSERT שמופיעות למעלה.

אחרי החיבור, מודל Gemini מבין את סכמת הגרף. עכשיו אתם יכולים להריץ מעברים מורכבים באמצעות שפה טבעית.

המודל יתרגם את הפקודות האלה ל-GQL (Graph Query Language) באופן אוטומטי:

זיהוי מבני רשת

"תאר את המבנה של גרף הנכסים FinGraph. מהן התוויות של הצמתים והקשתות?"

תשובה:

  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

זיהוי הונאות ומעגלים חוזרים

‫"Find any circular transfers where money was sent from Account A and eventually returned to Account A within 3 hops."

תשובה:

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.

ניתוח מעמיק של קשרים

"תזהה את כל האנשים שהם הבעלים של חשבונות ששלחו יותר מ-499 $לחשבונות שבבעלות אנשים שונים ב-24 החודשים האחרונים".

תשובה:

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

חיפוש נתיבים

‫"Find the shortest path of transfers between Account ID 16 and Account ID 20." ‏(איתור הנתיב הקצר ביותר של העברות בין מזהה חשבון 16 למזהה חשבון 20).

תשובה:

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. מעולה!

כל הכבוד, סיימתם את ה-Codelab.

מה נכלל

ב-codelab הזה למדתם איך להגדיר את gemini-cli עם שרת Spanner MCP ולשלוח שאילתות בשפה טבעית לנתוני Spanner Graph כדי לקבל תובנות. סיכום של נקודות הציון החשובות:

תשתית מנוהלת: הופעל שרת ה-MCP של Spanner מרחוק, כך שלא צריך פרוקסי מקומי או את MCP Toolbox.
שילוב של תרשים: הגדרנו תרשים מאפיינים של Spanner (FinGraph) עם צמתים וקשתות כדי לייצג קשרים מורכבים.
‫Native Tooling: חיברנו את Gemini CLI ישירות לנקודת הקצה המנוהלת של Spanner באמצעות סכימת URI רגילה.
‫SQL בשפה טבעית ו-GQL: הפעלנו את השרת עם הנחיות ספציפיות לגרף, כדי לאפשר ל-LLM לבצע מעברים מרובי-קפיצות וזיהוי מחזורים בלי קידוד ידני של SQL או GQL.
מוכנות לשימוש בארגונים: בדקנו איך MCP מנוהל מספק לסוכני AI נתיב מאומת וניתן להרחבה לאינטראקציה עם נתונים תפעוליים.