اربط مساعدك الذكي بقاعدة بياناتك مع MCP Toolbox من Google

بدل نسخ بيانات مشروعك إلى المحادثة كل مرة، يمكنك إتاحة أداة محددة للمساعد: البحث عن فندق بالاسم، مثلًا. يستدعي المساعد الأداة، وينفّذ الخادم الاستعلام على قاعدة البيانات، ثم تعود النتائج إلى التطبيق الذي تستخدمه.

هذا ما يتيحه مشروع MCP Toolbox for Databases الموجود في مستودع googleapis. يعمل خادمًا لبروتوكول MCP، وهو معيار لربط تطبيقات الذكاء الاصطناعي بالأدوات ومصادر البيانات. يدعم أدوات جاهزة لاستكشاف قواعد البيانات، وأدوات مخصصة تحدد أنت استعلاماتها ومدخلاتها.

هذه مراجعة مبنية على وثائق المشروع والكود المنشور، وليست تجربة تشغيل على قاعدة بياناتنا. المثال التالي إعداد تعليمي مقتبس بتعديلات من التوثيق الرسمي، والصورة من أمثلة المشروع نفسه.

لمن هذا؟

للمطوّر الذي يريد ربط مساعد برمجي أو تطبيق وكيل بقاعدة بيانات، ويعرف أساسيات الطرفية وSQL، لغة الاستعلام عن البيانات. يمكن أن تستخدمه أثناء تطوير تطبيق، أو لبناء أدوات محددة لوكيل يعمل داخل منتجك.

سنركّز على PostgreSQL وأداة بحث واحدة. لا تحتاج حساب Google Cloud لهذا المثال المحلي، ولا بطاقة رسومية لتشغيل خادم Toolbox نفسه؛ النموذج الذي تختاره لاحقًا له متطلبات وتكلفة منفصلتان.

إذا لم تستخدم قواعد البيانات من قبل، تعلّم أولًا إنشاء قاعدة تجريبية والاتصال بها. ربط مساعد ببيانات العملاء ليس خطوة مناسبة للتجربة الأولى.

ماذا ستحتاج؟

PostgreSQL يعمل بالفعل، وقاعدة تجريبية تحتوي بيانات وهمية.
برنامج psql للتحقق من الاتصال، وحساب قاعدة بيانات مخصص يستطيع قراءة الجدول المطلوب فقط. حساب إدارة القاعدة يُستخدم لتجهيز المثال، ولا نعطيه للمساعد.
نسخة Toolbox المناسبة لنظام التشغيل ومعمارية الجهاز. أوامر التنزيل أدناه تخص Linux بمعمارية AMD64، وتستخدم الإصدار 1.14.0 المذكور في مراجعة التوثيق.
ملف إعداد اسمه tools.yaml، ومتغيرات بيئة لبيانات الاتصال بدل وضع كلمة المرور داخل الملف.
متصفح لاختبار الأداة بواجهة Toolbox UI. ربطها لاحقًا بمساعد يحتاج تطبيقًا يدعم MCP، مثل Claude Code أو Gemini CLI، وفق إعدادات ذلك التطبيق.

المشروع مفتوح المصدر بترخيص Apache-2.0. هذا لا يجعل قاعدة بيانات مستضافة أو خدمة نموذج لغوي مجانية. وانتبه للخصوصية: تشغيل Toolbox محليًا لا يعني أن المساعد السحابي لن يتلقى نتائج الأدوات التي يطلبها. راجع مسار البيانات وسياسة مزوّد النموذج قبل استخدام معلومات حساسة.

النتيجة النهائية (صورة)

الهدف الأول أداة اسمها search-hotels-by-name تظهر في واجهة الاختبار، وتقبل اسمًا ثم تنفّذ استعلامًا محددًا مسبقًا. بعد التحقق منها تستطيع إتاحتها لتطبيق يدعم MCP.

مثال رسمي لواجهة Toolbox UI يعرض أداة search-hotels-by-name وحقل الاسم وزر Run Tool؛ خانة الاستجابة فارغة ولم يُنفّذ استعلام في هذه اللقطة

الصورة من توثيق المشروع، وليست من اختبارنا. توضح شكل الأداة الجاهزة للاختبار؛ لا تعرض نتائج بحث فعلية. سنحذف أدوات الحجز والتعديل الموجودة في المثال الرسمي ونبقي البحث فقط في إعدادنا التعليمي.

خطوات 1-2-3

1. جهّز بيانات تجريبية وتحقق من صلاحية القراءة

اطلب من مسؤول قاعدة البيانات تجهيز جدول hotels في قاعدة مخصصة للتجربة. هذا نموذج بيانات وهمية مبسّط، وليس نسخة من جدول إنتاج:

CREATE TABLE hotels (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL,
  location TEXT NOT NULL
);

INSERT INTO hotels (id, name, location) VALUES
  (1, 'Demo Hotel Basel', 'Basel'),
  (2, 'Demo Hotel Zurich', 'Zurich');

يمنح المسؤول حساب الاتصال المخصص صلاحية القراءة على هذا الجدول، مع صلاحيات الاتصال بالقاعدة والوصول إلى مخططها اللازمة. لا تستخدم حسابًا يملك صلاحيات إدارية أو صلاحية تعديل البيانات لهذا المثال.

اضبط المتغيرات POSTGRES_HOST وPOSTGRES_PORT وPOSTGRES_DATABASE وPOSTGRES_USER وPOSTGRES_PASSWORD في بيئة التشغيل المحلية، باستخدام آلية إدارة الأسرار المتاحة لك. لا تشارك قيمها في المحادثات أو Git. وللتحقق من الاتصال، نفّذ:

psql -h "$POSTGRES_HOST" -p "$POSTGRES_PORT" \
  -U "$POSTGRES_USER" -d "$POSTGRES_DATABASE" \
  -c 'SELECT id, name, location FROM hotels ORDER BY id;'

يطلب psql كلمة المرور وفق إعداد المصادقة لديك؛ POSTGRES_PASSWORD متغير يستخدمه ملف Toolbox هنا، وليس متغير كلمة المرور التلقائي لـpsql. إدخال كلمة المرور لا يظهر عادةً أثناء الكتابة.

علامة النجاح في هذه المرحلة أن يعرض الحساب صفوف الجدول. إذا فشل الاتصال المباشر، أصلح بيانات الاتصال والصلاحيات قبل إدخال المساعد في العملية.

2. عرّف أداة واحدة بدل إتاحة SQL مفتوح

نزّل الملف التنفيذي المناسب. هذا الأمر لـLinux AMD64 فقط:

curl -fL -o toolbox \
  https://storage.googleapis.com/mcp-toolbox-for-databases/v1.14.0/linux/amd64/toolbox

قبل تشغيل الملف، راجع تعليمات التحقق من التوقيع في توثيق التثبيت الرسمي. ثم:

chmod +x toolbox
./toolbox --version

أنشئ tools.yaml بالمحتوى التالي. تأكد من أن متغيرات البيئة متاحة للعملية التي ستشغّل Toolbox:

kind: source
name: my-pg-source
type: postgres
host: ${POSTGRES_HOST}
port: ${POSTGRES_PORT:5432}
database: ${POSTGRES_DATABASE}
user: ${POSTGRES_USER}
password: ${POSTGRES_PASSWORD}
---
kind: tool
name: search-hotels-by-name
type: postgres-sql
source: my-pg-source
description: Search demo hotels by name and return their location.
parameters:
  - name: name
    type: string
    description: Part of the hotel name to search for.
statement: |
  SELECT id, name, location
  FROM hotels
  WHERE name ILIKE '%' || $1 || '%'
  ORDER BY id
  LIMIT 20;
---
kind: toolset
name: hotel-search
tools:
  - search-hotels-by-name

source يعرّف الاتصال، وtool يعرّف العملية، وtoolset يجمع الأدوات التي تريد تحميلها معًا. يفصل الرمز --- بين هذه التعريفات داخل الملف نفسه.

في الاستعلام، يمثّل $1 قيمة الاسم التي ترسلها الأداة. يوضّح توثيق postgres-sql أن المعاملات العادية تدخل إلى استعلام مُحضّر. استخدمناها لقيمة البحث، ولم نسمح للمساعد باختيار اسم الجدول أو كتابة SQL كامل.

تجنب الخلط بينها وبين templateParameters التي تغيّر نص الاستعلام نفسه؛ يحذّر المشروع من مخاطر حقن SQL عند استخدامها. وحتى مع الاستعلام المخصص، تظل صلاحيات حساب قاعدة البيانات ضرورية. النص الموجود في وصف الأداة ليس حاجزًا أمنيًا.

3. اختبر الأداة، ثم اربطها بالمساعد

شغّل الخادم وواجهة الاختبار:

./toolbox --config tools.yaml --ui

افتح عنوان الواجهة الذي يعلنه الخادم، ثم اختر Tools وأداة search-hotels-by-name. أدخل Basel في حقل name واضغط Run Tool.

المتوقع مع البيانات التعليمية أعلاه أن يعود الصف الذي يحمل اسم Demo Hotel Basel. هذا توقع مبني على الاستعلام والبيانات، وليس نتيجة تنفيذ أجريناه. قارن الاستجابة بالاستعلام المباشر في psql، وتأكد من أن الواجهة لم تعرض أدوات حجز أو تعديل غير موجودة في إعدادك.

بعد نجاح الاختبار، يكون عنوان اتصال MCP المحلي للمجموعة المحددة:

http://127.0.0.1:5000/mcp/hotel-search

وتعرض الوثائق أيضًا المسار العام /mcp. طريقة إضافة العنوان تختلف بين التطبيقات؛ استخدم إعداد عميلك الخاص باتصال HTTP، ولا تفترض أن ملف إعداد Claude Code يطابق ملف VS Code.

يبين المثال التالي بنية اتصال HTTP المذكورة في README؛ ليس ملفًا موحدًا يصلح لكل عميل:

{
  "mcpServers": {
    "toolbox": {
      "type": "http",
      "url": "http://127.0.0.1:5000/mcp/hotel-search"
    }
  }
}

إذا كان العميل والخادم على الجهاز نفسه، يمكنك بعدها طلب: «استخدم أداة البحث للعثور على الفنادق التي يحتوي اسمها على Basel، واعرض الاسم والمدينة».

أما إذا كان العميل داخل حاوية أو على جهاز آخر، فلن يشير 127.0.0.1 إلى جهاز قاعدة البيانات تلقائيًا. تحتاج إعداد شبكة ومصادقة مناسبين، لا مجرد نسخ هذا العنوان. لا تعرض الخادم للإنترنت بغرض تجاوز مشكلة الاتصال.

مشاكل شائعة

يفشل الاتصال بقاعدة البيانات

قد تكون الخدمة متوقفة، أو العنوان والمنفذ غير صحيحين، أو الحساب يفتقد صلاحية الاتصال. جرّب psql من بيئة التشغيل نفسها أولًا. إذا كان Toolbox داخل حاوية، فتذكّر أن localhost داخلها يشير إلى الحاوية نفسها. لا تبدأ الحل بمنح الحساب كل الصلاحيات.

تعمل الواجهة لكن الأداة لا تظهر

راجع اسم الأداة في قسم toolset، ومسار الملف الذي مررته إلى --config، وسجل الخادم بحثًا عن خطأ في الإعداد. عند الاتصال بالمساعد، راجع أيضًا اسم المجموعة في عنوان /mcp/hotel-search. علامة التحقق هي ظهور الأداة المطلوبة في قائمة الأدوات، لا مجرد فتح صفحة الواجهة.

تنفّذ الأداة لكن لا تعود صفوف

تحقق من أن الجدول والبيانات موجودان في القاعدة التي اتصلت بها، وأن قيمة name تطابق جزءًا من اسم موجود. اختبر الاستعلام في psql باستخدام الحساب نفسه. نجاح الاتصال لا يثبت صحة البيانات أو منطق البحث.

أريد الاستكشاف السريع بدل كتابة tools.yaml

يوفر المشروع إعدادات جاهزة مثل --prebuilt=postgres، تشمل أدوات من نوع list_tables وexecute_sql. قد تناسب بيئة تطوير تجريبية، لكنها أوسع من أداة البحث المحددة هنا. وحتى المجموعة postgres/data تتضمن execute_sql؛ اختيارها لا يحوّل الاتصال إلى قراءة فقط.

ابدأ بحساب محدود الصلاحيات. لا تمنح مساعدًا أداة SQL عامة وحساب إدارة ثم تعتمد على جملة «لا تعدّل البيانات» في التعليمات. ولإجراءات الكتابة مستقبلًا، صمّم أدوات منفصلة وأضف موافقة بشرية وضوابط في التطبيق وقاعدة البيانات بحسب المهمة.

مصطلحات

MCP: بروتوكول يتيح لتطبيق الذكاء الاصطناعي اكتشاف أدوات خارجية واستدعاءها؛ لا يمنح الصلاحيات تلقائيًا.
خادم Toolbox: البرنامج الذي يستقبل استدعاء الأداة ويتعامل مع مصدر البيانات وفق الإعداد.
Source: تعريف مصدر البيانات وبيانات اتصاله داخل ملف الإعداد.
Toolset: مجموعة مسماة من الأدوات، يمكنك طلبها بدل تحميل جميع الأدوات.
الاستعلام ذو المعاملات: استعلام ثابت تدخل إليه قيم مثل اسم الفندق في مواضع محددة، بدل تركيب نص SQL من مدخلات المستخدم.
أقل صلاحية: إعطاء الحساب القدر اللازم للعمل فقط، مثل قراءة جدول بعينه بدل إدارة القاعدة كلها.

ماذا بعد؟

ابدأ بأداة قراءة واحدة، وقارن ناتجها مباشرةً بقاعدة البيانات، ثم اربطها بالمساعد. بعد ذلك أضف أداة بحث ثانية عند وجود حاجة واضحة لها، بدل إتاحة قاعدة البيانات كاملة من البداية.

إذا كانت حاجتك استكشاف الجداول أثناء التطوير، فراجع الإعدادات الجاهزة. وإذا كنت تبني ميزة داخل منتج، فالأدوات المخصصة تساعدك على تحديد الاستعلامات والمدخلات التي تتيحها. يدعم المشروع أيضًا قواعد أخرى، منها MySQL وBigQuery وRedis، لكن لكل تكامل إعداداته وصلاحياته؛ مثال PostgreSQL لا يختبرها ولا يغطيها.

ولفهم جانب المساعد والواجهة قبل إضافة قواعد البيانات، اقرأ اجمع نماذج الذكاء الاصطناعي في واجهة واحدة مع OpenWebUI.

المصادر ونسبة الصور

الغلاف يستخدم شعار MCP Toolbox الرسمي مع تصغيره والمحافظة على نسبته ووضعه على خلفية فاتحة. صورة واجهة الأداة من ملف docs/en/documentation/configuration/toolbox-ui/tools.png في المستودع نفسه، دون تعديل. نُقلت الأصول من المراجعة المرتبطة أعلاه ضمن مشروع مرخّص بترخيص Apache-2.0؛ نسخة الترخيص مرفقة بحزمة المقال. حقوق الأسماء والعلامات لأصحابها، واستخدامها هنا للتعريف بالمشروع، دون ادعاء رعاية أو اعتماد من Google.