درس تطبيقي حول الترميز: خادم MCP على Spanner

1. نظرة عامة

يوضّح هذا الدرس العملي كيفية إصدار طلبات بحث في الرسم البياني على Spanner باستخدام gemini-cli وخوادم بروتوكول سياق النموذج (MCP) من Google. من خلال دمج قاعدة بيانات Spanner المتعددة النماذج، بما في ذلك Spanner Graph، مع خدمة MCP المُدارة، يمكنك استخدام اللغة الطبيعية للكشف عن العلاقات المخفية في بياناتك، مثل دوائر الاحتيال أو تبعيات سلسلة التوريد، في قاعدة بيانات واحدة بدون كتابة طلبات بحث معقّدة بلغة GQL (لغة طلبات البحث في الرسوم البيانية) أو SQL يدويًا.

ما ستتعلمه

كيفية إعداد قاعدة بيانات متعددة النماذج في Spanner، بما في ذلك Spanner Graph لـ MCP
كيفية ربط Gemini CLI بنقطة نهاية خدمة Spanner بعيدة مُدارة
كيفية استخدام اللغة الطبيعية لإنشاء SQL مدمَج مع 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}

إنشاء مخطط قاعدة البيانات

أنشئ مثيلاً وقاعدة بيانات تتضمّن جداول قاعدة بيانات ورسمًا بيانيًا للعلاقات. يتتبّع هذا المخطط الحسابات والأشخاص وعمليات النقل بينهما.

ملاحظة: يمكنك تنفيذ عبارات تعريف البيانات هذه من Spanner Studio. يُرجى الاطّلاع على هذا الرابط للحصول على معلومات حول إنشاء قاعدة بيانات Spanner والاستعلام عنها من وحدة تحكّم Google Cloud Platform.

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، يمكنك تخطّي الخطوتَين التاليتَين والانتقال مباشرةً إلى الخطوة 3.

الحصول على مفتاح Gemini API

لاستخدام أحدث نماذج Gemini في Gemini CLI، يجب ضبطها باستخدام مصادقة مفتاح واجهة برمجة التطبيقات. يمكننا الحصول على مفتاح واجهة برمجة التطبيقات إما في Google AI Studio

انتقِل إلى Google AI Studio -> الحصول على مفتاح API في المتصفّح.
انقر على الزر Create API key على يسار الشاشة
في النافذة المنبثقة، اختَر مشروعك أو استورِده إذا لم يكن ظاهرًا هناك.

أنشئ مفتاح واجهة برمجة التطبيقات.
يمكنك نسخ المفتاح باستخدام زر النسخ على الجانب الأيسر.

تم إعداد المفتاح ويمكننا الآن استخدامه مع 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 وتخزين مفتاح واجهة برمجة التطبيقات لمصادقة 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.

ضبط Gemini CLI لاستخدام Spanner MCP

يجب إضافة عنصر آخر إلى ملف settings.json. أولاً، اخرج من واجهة سطر الأوامر Gemini (يمكنك الضغط على 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 في مشروعك الذي تم إعداده.

"يُرجى إدراج جميع مثيلات Spanner في مشروعي <project1> (استبدِلها بمعرّف مشروعك)"

الردّ:

The Spanner instances in your project are:
 [instance1]

"يُرجى إدراج جميع قواعد البيانات في <instance1> (استبدِلها بمثيلك)"

الردّ:

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

بعد ذلك، لنطلب من Gemini تذكُّر المثيل/قاعدة البيانات التي نفّذت فيها عبارات DDL وعبارات الإدراج في قسم إعداد Spanner:

"افترِض أنّه سيتم إرسال جميع طلبات البحث إلى قاعدة البيانات <your-db> في المثيل <your-instance> ما لم يُذكر خلاف ذلك"

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

رصد الاحتيال والدورات

"العثور على أي عمليات تحويل دائرية تم فيها إرسال الأموال من الحساب "أ" وإعادتها في النهاية إلى الحساب "أ" في غضون 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- تهانينا!

تهانينا على إكمال تجربة البرمجة.

المواضيع التي تناولناها

في هذا الدرس التطبيقي حول الترميز، تعرّفت على كيفية ضبط gemini-cli باستخدام خادم Spanner MCP وإصدار طلبات مكتوبة بلغة طبيعية مقابل بيانات Spanner Graph لعرض الإحصاءات. في ما يلي ملخّص لأهم الإنجازات:

البنية الأساسية المُدارة: تم تفعيل خادم MCP البعيد في Spanner، ما أدى إلى إزالة الحاجة إلى الخوادم الوكيلة المحلية أو "أدوات MCP".
دمج الرسوم البيانية: تم إعداد "رسم بياني للعقارات" في Spanner (FinGraph) مع عُقد وحواف لتمثيل العلاقات المعقّدة.
الأدوات المضمّنة: تم ربط Gemini CLI مباشرةً بنقطة نهاية Spanner المُدارة باستخدام نظام معرّف موارد موحّد (URI) عادي.
‫Natural Language SQL وGQL: تم اختبار الخادم باستخدام طلبات خاصة بالرسومات البيانية، ما سمح للنموذج اللغوي الكبير بإجراء عمليات اجتياز متعددة الخطوات ورصد الدورات بدون ترميز SQL/GQL يدوي.
الاستعداد للمؤسسات: استكشفنا كيف توفّر منصة MCP المُدارة مسارًا قابلاً للتوسّع ومصادقًا عليه لكي تتفاعل وكلاء الذكاء الاصطناعي مع البيانات التشغيلية.