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 นี้
gcloud CLI ติดตั้งและตรวจสอบสิทธิ์แล้ว
สิทธิ์เข้าถึง Gemini CLI

หมายเหตุ: คุณจะเรียกใช้คำสั่งทั้งหมดในเทอร์มินัล Unix โปรดดูข้อกำหนดเบื้องต้นด้านบนเพื่อรับสิทธิ์เข้าถึงเทอร์มินัลที่มีสิทธิ์เข้าถึง gcloud พร้อมการตรวจสอบสิทธิ์ที่เหมาะสม

2. ตั้งค่าสภาพแวดล้อมแบบหลายโมเดลของ Spanner

MCP ที่มีการจัดการจะทำงานได้ดีที่สุดเมื่อมีการกำหนดสคีมาฐานข้อมูลไว้ล่วงหน้า เราจะสร้างกราฟ "การตรวจหาการประพฤติมิชอบ" ทางการเงินโดยอิงตามตัวอย่างกราฟ Spanner

เปิดใช้ 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 เป็น Agent หลักในการดำเนินการส่วนใหญ่ และขั้นตอนแรกคือการกำหนดค่าให้ทำงานร่วมกับเซิร์ฟเวอร์ MCP ของ Spanner ระยะไกล นอกจากนี้ เราขอแนะนำอย่างยิ่งให้ใช้ 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 -> รับคีย์ API ในเบราว์เซอร์
คลิกปุ่ม 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

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 กัน

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 ทุกครั้งที่รีสตาร์ทเชลล์ ระบบอาจเปลี่ยนกลับไปใช้เวอร์ชันก่อนหน้า การเปลี่ยนแปลงที่คุณทำกับ 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 2 ครั้งได้)

ใน 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 ในโปรเจ็กต์ที่กำหนดค่ากันก่อน

"โปรดแสดงรายการอินสแตนซ์ Spanner ทั้งหมดในโปรเจ็กต์ <project1> (แทนที่ด้วยรหัสโปรเจ็กต์ของคุณ)"

คำตอบ:

The Spanner instances in your project are:
 [instance1]

"โปรดแสดงรายการฐานข้อมูลทั้งหมดใน <instance1> (แทนที่ด้วยอินสแตนซ์ของคุณ)"

คำตอบ:

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

การตรวจจับการประพฤติมิชอบและการอ้างอิงเป็นวงกลม

"ค้นหาการโอนแบบวงกลมที่มีการส่งเงินจากบัญชี ก และในที่สุดก็กลับมายังบัญชี ก ภายใน 3 ขั้นตอน"

คำตอบ:

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

การหาเส้นทาง

"ค้นหาเส้นทางการโอนที่สั้นที่สุดระหว่างรหัสบัญชี 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 เสร็จสมบูรณ์

สิ่งที่เราได้พูดถึงไปแล้ว

ในโค้ดแล็บนี้ คุณได้เรียนรู้วิธีกำหนดค่า gemini-cli ด้วยเซิร์ฟเวอร์ MCP ของ Spanner และออกคำค้นหาภาษาที่เป็นธรรมชาติกับข้อมูลกราฟ Spanner เพื่อแสดงข้อมูลเชิงลึก สรุปเหตุการณ์สำคัญมีดังนี้

โครงสร้างพื้นฐานที่มีการจัดการ: เปิดใช้เซิร์ฟเวอร์ MCP ของ Spanner ระยะไกล ซึ่งช่วยลดความจำเป็นในการใช้พร็อกซีภายในหรือกล่องเครื่องมือ MCP
การผสานรวมกราฟ: กำหนดค่ากราฟพร็อพเพอร์ตี้ Spanner (FinGraph) ด้วยโหนดและขอบเพื่อแสดงความสัมพันธ์ที่ซับซ้อน
เครื่องมือในตัว: เชื่อมต่อ Gemini CLI กับปลายทาง Spanner ที่มีการจัดการโดยตรงโดยใช้รูปแบบ URI มาตรฐาน
SQL และ GQL ภาษาธรรมชาติ: ฝึกฝนเซิร์ฟเวอร์ด้วยพรอมต์เฉพาะกราฟ ซึ่งช่วยให้ LLM สามารถดำเนินการข้ามหลายฮอปและการตรวจจับวงจรได้โดยไม่ต้องเขียนโค้ด SQL/GQL ด้วยตนเอง
ความพร้อมใช้งานระดับองค์กร: สำรวจวิธีที่ MCP ที่มีการจัดการมอบเส้นทางที่ปรับขนาดได้และมีการตรวจสอบสิทธิ์ให้เอเจนต์ AI โต้ตอบกับข้อมูลการดำเนินงาน