خادم Apache Doris MCP هو خدمة خلفية تعتمد على Python و FastAPI، تدعم بروتوكول سياق النموذج (MCP) للاتصال بقاعدة بيانات Apache Doris، وتنفيذ تحويل اللغة الطبيعية إلى SQL (NL2SQL)، وتنفيذ الاستعلامات وإدارة البيانات الوصفية.

نظرة عامة على مشروع Apache Doris MCP Server

Apache Doris MCP (بروتوكول سياق النموذج) Server هو خدمة خلفية مبنية على Python و FastAPI، تهدف إلى التكامل السلس مع قاعدة بيانات Apache Doris من خلال بروتوكول سياق النموذج (MCP). يوفر واجهات موحدة لوكلاء الذكاء الاصطناعي والعملاء، ويدعم وظائف مثل تحويل اللغة الطبيعية إلى SQL (NL2SQL)، وتنفيذ استعلامات SQL، وإدارة البيانات الوصفية، وتحليل البيانات. يعتبر هذا المشروع امتدادًا مهمًا لمجتمع Apache Doris، وهو مناسب بشكل خاص لسيناريوهات الأعمال التي تتطلب تفاعلًا فعالًا مع البيانات وتحليلًا ذكيًا.

منذ إصدار الإصدار 0.3.0 في عام 2025، شهد المشروع تحديثات معمارية كبيرة، حيث انتقل من الاتصال القائم على SSE (أحداث مرسلة من الخادم) إلى بروتوكول HTTP موحد قابل للتدفق، وأضاف إطار عمل أمان على مستوى المؤسسات ووظائف تحسين الأداء. الهدف الأساسي للمشروع هو ربط أنظمة الذكاء الاصطناعي بقاعدة بيانات Apache Doris من خلال بروتوكول MCP، لتحقيق استكشاف وتحليل ذكي للبيانات.

الوظائف الأساسية

يوفر Apache Doris MCP Server الوظائف الرئيسية التالية:

1. تحويل اللغة الطبيعية إلى SQL (NL2SQL)

   • يدعم إنشاء استعلامات SQL من خلال إدخال اللغة الطبيعية، بالاشتراك مع نماذج لغوية كبيرة (LLMs) لتحقيق إنشاء استعلامات ذكي.
   • مناسب لسيناريوهات حيث يحتاج مستخدمو الأعمال إلى الاستعلام عن البيانات دون كتابة SQL معقدة.

2. تنفيذ استعلامات SQL

   • يدعم تنفيذ أوامر SQL مباشرة من خلال أداة exec_query، مع إمكانية تخصيص اختيار قاعدة البيانات، وعدد الصفوف المحدود، وإعدادات المهلة.
   • يتضمن فحصًا أمنيًا مدمجًا (مثل الحماية من حقن SQL) وإضافة LIMIT تلقائية، لضمان أمان وكفاءة الاستعلام.

3. إدارة البيانات الوصفية

   • يوفر أدوات غنية لاستخراج البيانات الوصفية، بما في ذلك:
     • قائمة بجميع قواعد البيانات والجداول (get_all_databases, get_database_tables).
     • الحصول على هيكل الجدول والتعليقات ومعلومات الفهرس (get_table_schema, get_table_comment, get_column_comments, get_table_indexes).
     • يدعم اكتشاف الكتالوجات المتعددة (get_catalog_list).

4. الاستعلام عن سجلات التدقيق

   • الحصول على سجلات التدقيق الأخيرة من خلال get_recent_audit_logs، مع دعم نطاق زمني مخصص وقيود السجلات.

5. إطار عمل أمان على مستوى المؤسسات

   • يدعم طرق مصادقة متعددة (Token، Basic Auth، OAuth).
   • التحكم في الوصول المستند إلى الأدوار (RBAC)، يوفر أربعة مستويات أمان.
   • يتضمن حماية مدمجة من حقن SQL، والتحقق من الاستعلام، ووظائف إخفاء حساسية البيانات.

6. تحسين الأداء

   • تحسين تنفيذ الاستعلام، من خلال آليات التخزين المؤقت المحسنة وإدارة تجمع الاتصالات لتحسين الأداء.
   • يدعم مراقبة الأداء والتحليل الإحصائي (performance_stats).

7. أوضاع اتصال متعددة

   • Streamable HTTP: يدعم الطلب/الاستجابة والنقل المتدفق من خلال نقطة نهاية /mcp موحدة (src/streamable_server.py).
   • SSE (مهمل): تدعم الإصدارات السابقة الاتصال عبر نقاط النهاية /sse و /mcp/messages (src/sse_server.py).
   • Stdio (اختياري): من خلال التفاعل القياسي للإدخال/الإخراج (src/stdio_server.py).

8. وظائف تجريبية

   • تحليل إحصائيات الأعمدة (column_analysis)، يوفر رؤى حول البيانات.
   • دعم اتحاد الكتالوجات، مناسب لبيئات الكتالوجات المتعددة.

البنية التقنية

تصميم بنية المشروع معياري وفعال، ويتضمن المكونات الرئيسية التالية:

• الإطار الأساسي: مبني على Python 3.12 و FastAPI، ويوفر خدمة API عالية الأداء.
• تنفيذ بروتوكول MCP:
  • يوفر واجهات موحدة لاستدعاء الأدوات وإدارة الموارد والتفاعل مع المطالبات.
  • يعالج جميع الطلبات من خلال نقطة نهاية /mcp موحدة، مما يبسط التكامل.
• التفاعل مع قاعدة البيانات:
  • doris_mcp_server/utils/db.py: يوفر اتصال قاعدة البيانات (get_db_connection) ووظائف تنفيذ الاستعلام (execute_query, execute_query_df).
  • doris_mcp_server/utils/schema_extractor.py: فئة MetadataExtractor مسؤولة عن استخراج البيانات الوصفية، بما في ذلك آلية التخزين المؤقت.
  • doris_mcp_server/utils/sql_executor_tools.py: وظيفة execute_sql_query تغلف منطق الاستعلام، بما في ذلك الفحص الأمني وتسلسل النتائج.
• إدارة الأمان:
  • يدعم طرق مصادقة متعددة و RBAC.
  • يوفر الحماية من حقن SQL والتحقق من الاستعلام وتسجيل سجلات التدقيق.
• دعم النشر:
  • نشر صور Docker، وتكوين منفذ موحد (3000، 3001، 3002).
  • تكوين متغيرات البيئة (مثل DB_HOST, DB_PORT, DB_USER, DB_PASSWORD).

تطور البنية: قام الإصدار 0.3.0 بإزالة حوالي 300 سطر من التعليمات البرمجية القديمة لـ SSE، والانتقال إلى HTTP القابل للتدفق، وتوحيد تسمية الأدوات (إزالة البادئة mcp_doris_)، وزيادة درجة النمطية.

التثبيت والاستخدام

متطلبات البيئة

• Python 3.12 أو أعلى
• قاعدة بيانات Apache Doris (متصلة عبر بروتوكول MySQL)
• أداة إدارة الحزم (مثل uv أو pip)
• اختياري: Docker (للنشر في حاويات)

خطوات التثبيت

1. استنساخ المستودع:

git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server

2. تثبيت التبعيات: استخدم uv (موصى به) أو pip للتثبيت:

uv sync

أو

pip install -r requirements.txt

3. تكوين متغيرات البيئة: قم بإنشاء ملف .env أو قم بتعيين متغيرات البيئة مباشرة:

export DORIS_HOST=<doris-host>
export DORIS_PORT=<port>
export DORIS_USER=<doris-user>
export DORIS_PASSWORD=<doris-pwd>
export SERVER_PORT=3000

4. تشغيل الخادم:

uv run --with mcp-doris --python 3.13 mcp-doris

أو

python -m mcp_doris.mcp_server

5. التحقق من التشغيل: بعد التشغيل الناجح، يمكن التفاعل من خلال عميل MCP (مثل Cursor) أو متصفح MCP المدمج (http://localhost:5173).

اختبار الاتصال

قم بتشغيل البرنامج النصي للاختبار للتحقق من اتصال قاعدة البيانات:

python src/doris-mcp-server/test.py

الناتج المتوقع:

🚀 Doris MCP Server is starting...
[DorisConnector] Connected to 127.0.0.1:9030
✅ Database connection successful.
[DorisConnector] Connection closed.

سيناريوهات التطبيق

1. تحليل البيانات في الوقت الفعلي

   • بالاشتراك مع وظيفة NL2SQL، يمكن لمستخدمي الأعمال الاستعلام عن البيانات في الوقت الفعلي بلغة طبيعية، وإنشاء تقارير أو لوحات معلومات.
   • مناسب لدعم اتخاذ القرارات في الوقت الفعلي في صناعات مثل البيع بالتجزئة والمالية والاتصالات.

2. استكشاف البيانات الوصفية

   • يمكن لمهندسي البيانات الحصول بسرعة على مخطط قاعدة البيانات وهيكل الجدول ومعلومات الفهرس، وتسريع نمذجة البيانات وتحسينها.

3. الذكاء الاصطناعي المدفوع بالأعمال

   • دمج وكلاء الذكاء الاصطناعي (مثل Claude، Cursor)، وتحقيق أتمتة استعلام البيانات وتحليل سير العمل من خلال بروتوكول MCP.

4. إدارة الامتثال للأمان

   • إطار عمل أمان على مستوى المؤسسات ووظيفة سجلات التدقيق، تلبي متطلبات صناعات مثل التمويل والرعاية الصحية لأمن البيانات والامتثال.

5. بيئة الكتالوجات المتعددة

   • يدعم اتحاد الكتالوجات المتعددة، وهو مناسب لإدارة البيانات الوصفية والاستعلام في بيئات مستودعات البيانات المعقدة.

مزايا المشروع وقيوده

المزايا

• الذكاء: NL2SQL وتكامل LLM يقلل من حاجز استعلام البيانات.
• الأمان: المصادقة المتعددة و RBAC وحماية SQL تضمن أمانًا على مستوى المؤسسات.
• الأداء العالي: التخزين المؤقت وتجمع الاتصالات وتحسين الاستعلام يحسن الكفاءة.
• المرونة: يدعم أوضاع اتصال متعددة وتوسيع الأدوات المعيارية.

القيود

• استقرار الإصدارات المبكرة: بعض الوظائف (مثل column_analysis) تجريبية وقد تحتوي على أخطاء.
• الاعتماد على قاعدة بيانات Doris: مصمم بشكل أساسي لـ Apache Doris، والقدرة على التوافق مع قواعد بيانات بروتوكول MySQL الأخرى محدودة.
• إهمال SSE: قام الإصدار 0.3.0 بإزالة دعم SSE، ويجب الترحيل إلى HTTP القابل للتدفق.

ملخص

Apache Doris MCP Server هو أداة قوية ومرنة تربط قاعدة بيانات Apache Doris باحتياجات التحليل المدفوعة بالذكاء الاصطناعي. إن ميزاته مثل NL2SQL وإدارة البيانات الوصفية والأمان وتحسين الأداء تجعله يتمتع بإمكانات واسعة في تحليل البيانات في الوقت الفعلي وذكاء الأعمال وتطبيقات المؤسسات.