خادم MCP لـ ClickHouse، يوفر قدرات استعلام آمنة لقاعدة بيانات ClickHouse لمساعدي الذكاء الاصطناعي من خلال بروتوكول سياق النموذج (Model Context Protocol).

ملخص

خادم ClickHouse MCP هو تطبيق لخادم بروتوكول سياق النموذج (MCP) تم تطويره رسميًا بواسطة ClickHouse، وهو مصمم خصيصًا لتوفير اتصال آمن وقدرات تفاعل لقواعد بيانات ClickHouse لمساعدي الذكاء الاصطناعي (مثل Claude). يتيح هذا المشروع، من خلال بروتوكول MCP الموحد، لمساعدي الذكاء الاصطناعي تنفيذ استعلامات SQL وإدارة هياكل قواعد البيانات وإجراء تحليلات البيانات في الوقت الفعلي.

MCP (بروتوكول سياق النموذج) هو معيار مفتوح يهدف إلى توفير طريقة آمنة وموحدة لدمج الخدمات الخارجية لتطبيقات الذكاء الاصطناعي. من خلال هذا الخادم، يمكن للمستخدمين السماح لمساعدي الذكاء الاصطناعي بالوصول مباشرةً إلى قواعد بيانات ClickHouse الخاصة بهم، وتحقيق استعلامات وتحليلات بيانات ذكية.

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

1. تنفيذ استعلامات SQL (run_select_query)

• وصف الوظيفة: تنفيذ استعلامات SQL على مجموعة ClickHouse.
• آلية الأمان: يتم تشغيل جميع الاستعلامات في وضع readonly = 1 لضمان أمان البيانات.
• معلمات الإدخال:
  • sql (نص): عبارة استعلام SQL المراد تنفيذها.
• سيناريوهات الاستخدام: استرجاع البيانات، التحليل الإحصائي، إنشاء التقارير.

2. إدارة قواعد البيانات (list_databases)

• وصف الوظيفة: سرد جميع قواعد البيانات في مجموعة ClickHouse.
• الغرض: استكشاف هيكل قاعدة البيانات، التحقق من الأذونات.
• محتويات الإرجاع: قائمة بقواعد البيانات التي يمكن الوصول إليها.

3. إدارة الجداول (list_tables)

• وصف الوظيفة: سرد جميع الجداول في قاعدة بيانات محددة.
• معلمات الإدخال:
  • database (نص): اسم قاعدة البيانات.
• الغرض: استكشاف هيكل الجدول، فهم نموذج البيانات.

التكوين والنشر

التكامل مع Claude Desktop

مسار التكوين على نظام macOS

~/Library/Application Support/Claude/claude_desktop_config.json

مسار التكوين على نظام Windows

%APPDATA%/Claude/claude_desktop_config.json

مثال على التكوين الأساسي

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

تكوين متغيرات البيئة

المتغيرات المطلوبة

• CLICKHOUSE_HOST: اسم مضيف خادم ClickHouse.
• CLICKHOUSE_USER: اسم مستخدم المصادقة.
• CLICKHOUSE_PASSWORD: كلمة مرور المصادقة.

المتغيرات الاختيارية

• CLICKHOUSE_PORT: رقم المنفذ.
  • الافتراضي: 8443 عند تمكين HTTPS، و 8123 عند تعطيله.
• CLICKHOUSE_SECURE: تمكين/تعطيل اتصال HTTPS.
  • الافتراضي: "true"
• CLICKHOUSE_VERIFY: تمكين/تعطيل التحقق من شهادة SSL.
  • الافتراضي: "true"
• CLICKHOUSE_CONNECT_TIMEOUT: مهلة الاتصال (بالثواني).
  • الافتراضي: "30"
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: مهلة الإرسال/الاستقبال (بالثواني).
  • الافتراضي: "300"
• CLICKHOUSE_DATABASE: قاعدة البيانات الافتراضية للاتصال بها.
  • الافتراضي: لا يوجد (يستخدم الافتراضي للخادم).

سيناريوهات الاستخدام

1. تكوين ساحة تدريب ClickHouse SQL

{
  "env": {
    "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
    "CLICKHOUSE_PORT": "8443",
    "CLICKHOUSE_USER": "demo",
    "CLICKHOUSE_PASSWORD": "",
    "CLICKHOUSE_SECURE": "true",
    "CLICKHOUSE_VERIFY": "true"
  }
}

2. تكوين بيئة التطوير المحلية

# تكوين ملف .env
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_VERIFY=false

3. تكوين ClickHouse Cloud

CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password
# استخدام إعدادات الأمان الافتراضية

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

تجهيز البيئة

# تثبيت التبعيات
uv sync

# تفعيل البيئة الافتراضية
source .venv/bin/activate

# تشغيل خادم التطوير
mcp dev mcp_clickhouse/mcp_server.py

عملية الاختبار

# تثبيت تبعيات التطوير
uv sync --all-extras --dev

# فحص الكود
uv run ruff check .

# تشغيل خدمات الاختبار
docker compose up -d test_services

# تشغيل الاختبارات
uv run pytest tests

اعتبارات الأمان

إدارة أذونات قاعدة البيانات

• مبدأ أقل الامتيازات: يجب أن يمتلك مستخدم قاعدة بيانات MCP الحد الأدنى الضروري من الأذونات فقط.
• تجنب حسابات المسؤول: يحظر استخدام المستخدمين الافتراضيين أو المسؤولين.
• وضع القراءة فقط: يتم تنفيذ جميع الاستعلامات في وضع القراءة فقط لمنع تعديل البيانات.

أمان الشبكة

• اتصال HTTPS: يوصى بتمكين HTTPS في بيئات الإنتاج.
• التحقق من الشهادة: قم بتمكين التحقق من شهادة SSL لضمان أمان الاتصال.
• إعدادات المهلة: قم بتعيين مهلات اتصال واستعلام معقولة لمنع استهلاك الموارد.

الخصائص التقنية

التوافقية

• إصدار Python: يدعم Python 3.13.
• إدارة التبعيات: يستخدم uv لإدارة الحزم.
• الحاويات: يدعم نشر Docker.
• عبر الأنظمة الأساسية: يدعم macOS و Windows و Linux.

تحسين الأداء

• تجميع الاتصالات: إدارة فعالة لاتصالات قاعدة البيانات.
• التحكم في المهلة: مهلات اتصال واستعلام قابلة للتكوين.
• دعم غير متزامن: يدعم تنفيذ الاستعلامات غير المتزامنة.

ملخص

يقدم مشروع خادم ClickHouse MCP جسرًا آمنًا وفعالًا بين مساعدي الذكاء الاصطناعي وقواعد بيانات ClickHouse. من خلال بروتوكول MCP الموحد، فإنه يمكّن مساعدي الذكاء الاصطناعي من فهم وتشغيل هياكل قواعد البيانات المعقدة، وتنفيذ استعلامات SQL متطورة، وتوفير رؤى بيانات في الوقت الفعلي.

المزايا الرئيسية

1. دعم رسمي: تتم صيانته رسميًا بواسطة ClickHouse، مما يضمن التوافق والاستقرار.
2. تصميم آمن: وضع القراءة فقط المدمج والتحكم في الأذونات لحماية أمان البيانات.
3. سهولة التكامل: بروتوكول MCP الموحد يبسط تكامل تطبيقات الذكاء الاصطناعي.
4. تكوين مرن: يدعم سيناريوهات نشر متعددة، من التطوير المحلي إلى الإنتاج السحابي.
5. صديق للمطور: سلسلة أدوات تطوير كاملة وإطار اختبار.

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

• تحليل البيانات: السماح لمساعدي الذكاء الاصطناعي بالمساعدة في مهام تحليل البيانات المعقدة.
• ذكاء الأعمال: أتمتة إنشاء التقارير ورؤى البيانات.
• المراقبة في الوقت الفعلي: الجمع بين الذكاء الاصطناعي لمراقبة النظام ومقاييس الأعمال.
• استكشاف البيانات: استكشاف هيكل ومحتوى قاعدة البيانات من خلال استعلامات اللغة الطبيعية.

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