कोडलैब: Spanner MCP Server

1. खास जानकारी

इस कोडलैब में बताया गया है कि gemini-cli और Google के मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) सर्वर का इस्तेमाल करके, Spanner पर ग्राफ़ क्वेरी कैसे की जाती हैं. Spanner की मैनेज की गई एमसीपी सेवा के साथ Spanner के मल्टीमॉडल डेटाबेस (इसमें Spanner Graph भी शामिल है) को इंटिग्रेट करके, अपने डेटा में छिपे हुए संबंधों का पता लगाने के लिए नैचुरल लैंग्वेज का इस्तेमाल किया जा सकता है. जैसे, धोखाधड़ी करने वाले लोगों के ग्रुप या सप्लाई चेन की निर्भरता. इसके लिए, आपको एक ही डेटाबेस में जटिल GQL (ग्राफ़ क्वेरी लैंग्वेज) या एसक्यूएल क्वेरी को मैन्युअल तरीके से लिखने की ज़रूरत नहीं होती.

आपको क्या सीखने को मिलेगा

MCP के लिए, Spanner Graph के साथ-साथ Spanner मल्टी-मॉडल डेटाबेस को कैसे सेट अप करें.
Gemini CLI को मैनेज की गई रिमोट Spanner सेवा के एंडपॉइंट से कनेक्ट करने का तरीका.
नैचुरल लैंग्वेज का इस्तेमाल करके, GQL के साथ अपने-आप इंटिग्रेट होने वाले एसक्यूएल को जनरेट करने का तरीका. इससे, रिलेशनल ऑपरेशन के साथ-साथ ग्राफ़ ट्रैवर्सल और पैटर्न मैचिंग की जा सकती है.
एआई वर्कफ़्लो में ग्राफ़ डेटा को सुरक्षित रखने के सबसे सही तरीके.

ज़रूरी शर्तें

बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट.
टर्मिनल (जैसे, Cloud Shell) का ऐक्सेस. यह कोडलैब देखें.
gcloud सीएलआई इंस्टॉल किया गया हो और उसकी पुष्टि की गई हो.
Gemini CLI का ऐक्सेस.

ध्यान दें: आपको सभी निर्देश, Unix टर्मिनल में चलाने होंगे. gcloud को सही तरीके से पुष्टि करके ऐक्सेस करने वाले टर्मिनल का ऐक्सेस पाने के लिए, कृपया ऊपर दी गई ज़रूरी शर्तें देखें.

2. Spanner मल्टी-मॉडल एनवायरमेंट सेट अप करना

मैनेज किए गए एमसीपी का इस्तेमाल तब सबसे सही होता है, जब डेटाबेस स्कीमा पहले से तय किया गया हो. हम Spanner Graph के सैंपल के आधार पर, "धोखाधड़ी का पता लगाने" वाला फ़ाइनेंशियल ग्राफ़ बनाएंगे.

एपीआई चालू करें

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 से चलाया जा सकता है. GCP कंसोल से Spanner डेटाबेस बनाने और क्वेरी करने के बारे में जानकारी पाने के लिए, कृपया यह लिंक देखें.

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 के नए मॉडल का इस्तेमाल करने के लिए कॉन्फ़िगर किया है, तो अगले दो चरणों को छोड़कर सीधे तीसरे चरण पर जाएं.

Gemini API पासकोड पाना

Gemini CLI में Gemini के नए मॉडल इस्तेमाल करने के लिए, इसे एपीआई पासकोड की पुष्टि करने की सुविधा के साथ कॉन्फ़िगर करना होगा. हमें एपीआई पासकोड, Google AI Studio में मिल सकता है

अपने ब्राउज़र में Google AI Studio -> एपीआई पासकोड पाएं पर जाएं.
स्क्रीन की दाईं ओर मौजूद, Create API key बटन पर क्लिक करें
पॉप-अप विंडो में अपना प्रोजेक्ट चुनें या अगर वह वहां नहीं दिख रहा है, तो उसे इंपोर्ट करें

एपीआई पासकोड बनाएं.
दाईं ओर मौजूद 'कॉपी करें' बटन का इस्तेमाल करके, कुंजी को कॉपी किया जा सकता है.

कुंजी तैयार हो गई है. अब इसका इस्तेमाल Gemini CLI के लिए किया जा सकता है

Gemini CLI को कॉन्फ़िगर करना

Gemini CLI को सेटिंग कॉन्फ़िगरेशन फ़ाइल के ज़रिए कॉन्फ़िगर किया जा सकता है. इसके अलावा, /settings कमांड का इस्तेमाल करके इंटरैक्टिव तरीके से भी कॉन्फ़िगर किया जा सकता है. हम चाहते हैं कि हमारी सेटिंग, सेटिंग फ़ाइल में सेव रहें.

सबसे पहले, हम अपने प्रोजेक्ट के लिए एक डायरेक्ट्री बनाएंगे. आइए, डायरेक्ट्री को projectspannermcp कहते हैं और इन निर्देशों का इस्तेमाल करके उस डायरेक्ट्री पर स्विच करते हैं.

mkdir ~/projectspannermcp
cd ~/projectspannermcp

इस डायरेक्ट्री में, हम Gemini कॉन्फ़िगरेशन फ़ाइलों के लिए एक डायरेक्ट्री बनाएंगे और सभी कमांड चलाएंगे. Gemini सीएलआई, डिफ़ॉल्ट रूप से उपयोगकर्ता के स्कोप वाली कॉन्फ़िगरेशन फ़ाइल और ~/.gemini डायरेक्ट्री में इंस्टॉल किए गए एक्सटेंशन का इस्तेमाल करता है. हालांकि, हम ~/projectspannermcp डायरेक्ट्री में, अपने प्रोजेक्ट स्कोप का कॉन्फ़िगरेशन बनाएंगे. आइए, कॉन्फ़िगरेशन डायरेक्ट्री और फ़ाइलें बनाने से शुरुआत करें.

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

इसके बाद, हम क्लाउड शेल एडिटर का इस्तेमाल करके ~/projectspannermcp/.gemini/settings.json फ़ाइल खोलते हैं.

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 का इस्तेमाल करना है. साथ ही, Gemini CLI के लिए पुष्टि करने वाले एपीआई पासकोड को एनवायरमेंट वैरिएबल के तौर पर सेव करें. जब आईडीई शुरू होगा, तब यह वैरिएबल अपने-आप पिक हो जाएगा.

Cloud Shell एडिटर का इस्तेमाल करके फ़ाइल में बदलाव करना

edit ~/projectspannermcp/.env

साथ ही, ऊपर दिए गए "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 मॉडल का इस्तेमाल करना ज़रूरी है.

Spanner MCP का इस्तेमाल करने के लिए, Gemini CLI को कॉन्फ़िगर करना

हमें settings.json फ़ाइल में एक और चीज़ जोड़नी है. सबसे पहले, Gemini CLI से बाहर निकलें. इसके लिए, Ctrl+C को दो बार दबाएं.

ऊपर दिए गए settings.json में, हम 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 इंस्टेंस की सूची बनाकर शुरू करते हैं.

"कृपया मेरे प्रोजेक्ट <project1> (इसे अपने प्रोजेक्ट आईडी से बदलें) में मौजूद सभी Spanner इंस्टेंस की सूची बनाओ"

जवाब:

The Spanner instances in your project are:
 [instance1]

"कृपया <instance1> (इसे अपने इंस्टेंस से बदलें) में मौजूद सभी डेटाबेस की सूची बनाएं"

जवाब:

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

इसके बाद, Gemini को उस इंस्टेंस/डेटाबेस के बारे में बताते हैं जहां आपने Spanner सेटअप सेक्शन में DDL स्टेटमेंट और INSERT स्टेटमेंट चलाए थे:

"मान लें कि सभी क्वेरी, इंस्टेंस <your-instance> में मौजूद डेटाबेस <your-db> के ख़िलाफ़ सबमिट की जानी हैं. हालांकि, अगर कोई दूसरा डेटाबेस इस्तेमाल करना है, तो उसके बारे में साफ़ तौर पर बताएं"

NOTE: कृपया उस इंस्टेंस/डेटाबेस का इस्तेमाल करें जिसके ख़िलाफ़ आपने ऊपर दिए गए DDL स्टेटमेंट और इंसर्ट स्टेटमेंट चलाए थे.

कनेक्ट होने के बाद, Gemini मॉडल ग्राफ़ स्कीमा को समझ लेता है. अब आम बोलचाल की भाषा का इस्तेमाल करके, बेहतर तरीके से ट्रैवर्सल किया जा सकता है.

मॉडल, इन्हें अपने-आप GQL (ग्राफ़ क्वेरी लैंग्वेज) में अनुवादित कर देगा:

नेटवर्क स्ट्रक्चर की पहचान करना

"‘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

धोखाधड़ी और साइकल का पता लगाना

"ऐसे सभी सर्कुलर ट्रांसफ़र का पता लगाओ जिनमें खाता A से पैसे भेजे गए थे और तीन हॉप के अंदर वापस खाता A में आ गए थे."

जवाब:

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.

गहराई से संबंध का विश्लेषण

"उन सभी लोगों की पहचान करो जिनके खातों से, पिछले 24 महीनों में अलग-अलग लोगों के खातों में 499 डॉलर से ज़्यादा भेजे गए हैं."

जवाब:

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. बधाई हो!

कोडलैब पूरा करने के लिए बधाई.

हमने क्या-क्या कवर किया है

इस कोडलैब में, आपने Spanner MCP सर्वर के साथ gemini-cli को कॉन्फ़िगर करने का तरीका सीखा. साथ ही, आपने Spanner Graph डेटा के बारे में नैचुरल लैंग्वेज क्वेरी जारी करके अहम जानकारी पाने का तरीका सीखा. यहां मुख्य गतिविधियों की खास जानकारी दी गई है:

मैनेज किया गया इन्फ़्रास्ट्रक्चर: रिमोट Spanner MCP सर्वर चालू किया गया. इससे लोकल प्रॉक्सी या MCP टूलबॉक्स की ज़रूरत नहीं रही.
ग्राफ़ इंटिग्रेशन: जटिल संबंधों को दिखाने के लिए, नोड और किनारों के साथ Spanner प्रॉपर्टी ग्राफ़ (FinGraph) को कॉन्फ़िगर किया गया.
नेटिव टूलिंग: Gemini CLI को स्टैंडर्ड यूआरआई स्कीम का इस्तेमाल करके, सीधे तौर पर मैनेज किए गए Spanner एंडपॉइंट से कनेक्ट किया गया.
नैचुरल लैंग्वेज एसक्यूएल और जीक्यूएल: सर्वर को ग्राफ़ से जुड़े प्रॉम्प्ट दिए गए. इससे एलएलएम, मैन्युअल एसक्यूएल/जीक्यूएल कोडिंग के बिना मल्टी-हॉप ट्रैवर्सल और साइकल का पता लगा सका.
एंटरप्राइज़ के लिए तैयार: इसमें यह पता लगाया गया है कि मैनेज किए गए एमसीपी, एआई एजेंट को ऑपरेशनल डेटा के साथ इंटरैक्ट करने के लिए, पुष्टि किया गया और आसानी से बढ़ाया जा सकने वाला पाथ कैसे उपलब्ध कराते हैं.