mcp-dbutils

<div dir="rtl"> # دليل التثبيت *[English](../en/installation.md) | [中文](../zh/installation.md) | [Français](../fr/installation.md) | [Español](../es/installation.md) | العربية | [Русский](../ru/installation.md)* يقدم هذا المستند خطوات بسيطة وسهلة المتابعة لتثبيت وتكوين MCP Database Utilities، مما يسمح لمساعد الذكاء الاصطناعي الخاص بك بالوصول إلى قواعد البياناتك وتحليلها بأمان. ## ما هو MCP؟ MCP (Model Context Protocol) هو بروتوكول يسمح لتطبيقات الذكاء الاصطناعي (مثل Claude) باستخدام أدوات خارجية. MCP Database Utilities هي إحدى هذه الأدوات التي تمكن الذكاء الاصطناعي من قراءة محتوى قاعدة البيانات الخاصة بك دون تعديل أي بيانات. ## قبل أن تبدأ قبل بدء التثبيت، يرجى التأكد من أن لديك: - تطبيق ذكاء اصطناعي متوافق مع MCP (مثل Claude Desktop أو Cursor، إلخ) - قاعدة بيانات واحدة على الأقل تريد أن يصل إليها الذكاء الاصطناعي (SQLite أو MySQL أو PostgreSQL) ## اختر طريقة التثبيت الخاصة بك نقدم أربع طرق تثبيت بسيطة. اختر الطريقة التي تناسبك بشكل أفضل: | طريقة التثبيت | الأفضل لـ | المزايا | |---------|---------|------| | **الخيار أ: استخدام uvx** | معظم المستخدمين | بسيط وسريع، موصى به | | **الخيار ب: استخدام Docker** | المستخدمين الذين يفضلون التطبيقات المحتواة | بيئة معزولة | | **الخيار ج: استخدام Smithery** | مستخدمي Claude Desktop | تثبيت بنقرة واحدة، الأسهل | | **الخيار د: التثبيت بدون اتصال** | المستخدمين في بيئات بدون إنترنت | لا حاجة لاتصال شبكة | ## الخيار أ: استخدام uvx (موصى به) ### الخطوة 1: تثبيت أداة uv **على Mac أو Linux**: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` **على Windows**: ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` بعد التثبيت، تحقق من أنه يعمل بكتابة هذا الأمر في الطرفية الخاصة بك: ```bash uv --version ``` يجب أن ترى شيئًا مثل `uv 0.5.5` في الناتج. ### الخطوة 2: إنشاء ملف تكوين قاعدة البيانات 1. قم بإنشاء ملف يسمى `config.yaml` على جهاز الكمبيوتر الخاص بك 2. انسخ المحتوى التالي إلى الملف (اختر الذي يتطابق مع نوع قاعدة البيانات الخاصة بك): **مثال قاعدة بيانات SQLite**: ```yaml connections: my_sqlite: type: sqlite path: C:/path/to/your/database.db ``` **مثال قاعدة بيانات PostgreSQL**: ```yaml connections: my_postgres: type: postgres host: localhost port: 5432 dbname: my_database user: postgres_user password: postgres_password ``` **مثال قاعدة بيانات MySQL**: ```yaml connections: my_mysql: type: mysql host: localhost port: 3306 database: my_database user: mysql_user password: mysql_password ``` > يرجى استبدال معلومات المثال بتفاصيل قاعدة البيانات الفعلية الخاصة بك. لمزيد من خيارات التكوين، راجع [دليل التكوين](configuration.md). ### الخطوة 3: تكوين تطبيق الذكاء الاصطناعي الخاص بك #### تكوين Claude Desktop 1. افتح تطبيق Claude Desktop 2. انقر على أيقونة الإعدادات في الجزء السفلي الأيسر 3. حدد "MCP Servers" 4. انقر على "Add Server" 5. أضف التكوين التالي: ```json "dbutils": { "command": "uvx", "args": [ "mcp-dbutils", "--config", "C:/Users/YourUsername/config.yaml" ] } ``` > مهم: استبدل `C:/Users/YourUsername/config.yaml` بالمسار الفعلي لملف التكوين الذي أنشأته في الخطوة 2. #### تكوين Cursor 1. افتح تطبيق Cursor 2. اذهب إلى "Settings" → "MCP" 3. انقر على "Add MCP Server" 4. املأ المعلومات التالية: - Name: `Database Utility MCP` - Type: `Command` (افتراضي) - Command: `uvx mcp-dbutils --config C:/Users/YourUsername/config.yaml` > مهم: استبدل `C:/Users/YourUsername/config.yaml` بالمسار الفعلي لملف التكوين الذي أنشأته في الخطوة 2. ## الخيار ب: استخدام Docker ### الخطوة 1: تثبيت Docker إذا لم يكن لديك Docker مثبتًا، قم بتنزيله وتثبيته من [docker.com](https://www.docker.com/products/docker-desktop/). ### الخطوة 2: إنشاء ملف تكوين قاعدة البيانات نفس الخطوة 2 في الخيار أ، قم بإنشاء ملف `config.yaml`. ### الخطوة 3: الحصول على كود المشروع وبناء صورة Docker 1. أولاً، احصل على كود المشروع (اختر إحدى الطرق التالية): - استنساخ المشروع من GitHub: `git clone https://github.com/donghao1393/mcp-dbutils.git` - أو قم بتنزيل أحدث إصدار من [صفحة الإصدارات](https://github.com/donghao1393/mcp-dbutils/releases) واستخراجه 2. انتقل إلى دليل المشروع: ```bash cd mcp-dbutils ``` 3. قم ببناء صورة Docker: ```bash docker build -t mcp/dbutils . ``` > **ملاحظة**: يحتوي دليل المشروع الجذر بالفعل على Dockerfile، لذلك لا تحتاج إلى إنشاء واحد يدويًا. للتحديث إلى أحدث إصدار، ستحتاج إلى الحصول على أحدث كود وإعادة بناء الصورة. ### الخطوة 4: تكوين تطبيق الذكاء الاصطناعي الخاص بك #### تكوين Claude Desktop 1. افتح تطبيق Claude Desktop 2. انقر على أيقونة الإعدادات في الجزء السفلي الأيسر 3. حدد "MCP Servers" 4. انقر على "Add Server" 5. أضف التكوين التالي: ```json "dbutils": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "C:/Users/YourUsername/config.yaml:/app/config.yaml", "mcp/dbutils", "--config", "/app/config.yaml" ] } ``` > مهم: استبدل `C:/Users/YourUsername/config.yaml` بالمسار الفعلي لملف التكوين الذي أنشأته في الخطوة 2. #### تكوين Cursor 1. افتح تطبيق Cursor 2. اذهب إلى "Settings" → "MCP" 3. انقر على "Add MCP Server" 4. املأ المعلومات التالية: - Name: `Database Utility MCP` - Type: `Command` (افتراضي) - Command: `docker run -i --rm -v C:/Users/YourUsername/config.yaml:/app/config.yaml mcp/dbutils --config /app/config.yaml` > مهم: استبدل `C:/Users/YourUsername/config.yaml` بالمسار الفعلي لملف التكوين الذي أنشأته في الخطوة 2. ## الخيار ج: استخدام Smithery (نقرة واحدة لـ Claude) إذا كنت تستخدم Claude Desktop، فهذه هي طريقة التثبيت الأبسط: 1. تأكد من أن لديك Node.js مثبتًا 2. افتح الطرفية أو موجه الأوامر 3. قم بتشغيل الأمر التالي: ```bash npx -y @smithery/cli install @donghao1393/mcp-dbutils --client claude ``` 4. اتبع المطالبات على الشاشة لإكمال التثبيت تتعامل هذه الطريقة تلقائيًا مع جميع التكوينات، لذلك لا تحتاج إلى تعديل أي ملفات يدويًا. ## الخيار د: التثبيت بدون اتصال إذا كنت بحاجة إلى استخدام الأداة في بيئة بدون وصول إلى الإنترنت، أو ترغب في استخدام إصدار محدد: ### الخطوة 1: الحصول على الكود المصدري في بيئة بها وصول إلى الإنترنت: 1. قم بتنزيل الكود المصدري من GitHub: `git clone https://github.com/donghao1393/mcp-dbutils.git` 2. أو قم بتنزيل ملف zip من [صفحة الإصدارات](https://github.com/donghao1393/mcp-dbutils/releases) 3. انسخ الملفات التي تم تنزيلها إلى بيئتك غير المتصلة ### الخطوة 2: إنشاء ملف تكوين قاعدة البيانات نفس الخطوة 2 في الخيار أ، قم بإنشاء ملف `config.yaml`. ### الخطوة 3: تكوين تطبيق الذكاء الاصطناعي الخاص بك #### تكوين Claude Desktop 1. افتح تطبيق Claude Desktop 2. انقر على أيقونة الإعدادات في الجزء السفلي الأيسر 3. حدد "MCP Servers" 4. انقر على "Add Server" 5. أضف التكوين التالي: ```json "dbutils": { "command": "uv", "args": [ "--directory", "C:/Users/YourUsername/mcp-dbutils", "run", "mcp-dbutils", "--config", "C:/Users/YourUsername/config.yaml" ] } ``` > مهم: استبدل المسارات بالمسارات الفعلية لدليل الكود المصدري وملف التكوين الخاص بك. ## التحقق من التثبيت الخاص بك بعد إكمال التثبيت، دعنا نتحقق من أن كل شيء يعمل بشكل صحيح: ### اختبار الاتصال 1. افتح تطبيق الذكاء الاصطناعي الخاص بك (Claude Desktop أو Cursor) 2. اسأل الذكاء الاصطناعي الخاص بك: **"هل يمكنك التحقق مما إذا كنت قادرًا على الاتصال بقاعدة البيانات الخاصة بي؟"** 3. إذا تم تكوينه بشكل صحيح، سيرد الذكاء الاصطناعي بأنه اتصل بنجاح بقاعدة البيانات الخاصة بك ### جرب أوامر بسيطة بمجرد الاتصال، يمكنك تجربة هذه الأوامر البسيطة: - **"قم بسرد جميع الجداول في قاعدة البيانات الخاصة بي"** - **"صف بنية جدول العملاء"** - **"استعلم عن أغلى 5 منتجات في جدول المنتجات"** ## استكشاف المشكلات الشائعة وإصلاحها ### المشكلة 1: الذكاء الاصطناعي لا يستطيع العثور على أمر uvx **العرض**: يرد الذكاء الاصطناعي بـ "لم يتم العثور على أمر uvx" أو خطأ مشابه **الحل**: 1. تأكد من تثبيت uv بشكل صحيح: قم بتشغيل `uv --version` في الطرفية الخاصة بك 2. إذا كان مثبتًا ولكن لا تزال تحصل على أخطاء، فقد تكون مشكلة متغير البيئة: - في Windows، تحقق مما إذا كان متغير البيئة PATH يتضمن دليل تثبيت uv - في Mac/Linux، قد تحتاج إلى إعادة تشغيل الطرفية الخاصة بك أو تشغيل `source ~/.bashrc` أو `source ~/.zshrc` ### المشكلة 2: لا يمكن الاتصال بقاعدة البيانات **العرض**: يبلغ الذكاء الاصطناعي أنه لا يمكنه الاتصال بقاعدة البيانات الخاصة بك **الحل**: 1. **تحقق مما إذا كانت قاعدة البيانات الخاصة بك قيد التشغيل**: تأكد من بدء تشغيل خادم قاعدة البيانات الخاص بك 2. **تحقق من معلومات الاتصال**: تحقق بعناية من المضيف والمنفذ واسم المستخدم وكلمة المرور في ملف config.yaml الخاص بك 3. **تحقق من إعدادات الشبكة**: - إذا كنت تستخدم Docker، بالنسبة لقواعد البيانات المحلية، استخدم `host.docker.internal` كاسم المضيف - تأكد من أن جدران الحماية لا تمنع الاتصال ### المشكلة 3: خطأ في مسار ملف التكوين **العرض**: يبلغ الذكاء الاصطناعي أنه لا يمكنه العثور على ملف التكوين **الحل**: 1. **استخدم مسارات مطلقة**: تأكد من استخدام مسارات مطلقة كاملة في تكوين تطبيق الذكاء الاصطناعي الخاص بك 2. **تحقق من أذونات الملف**: تأكد من أن ملف التكوين قابل للقراءة من قبل المستخدم الحالي 3. **تجنب الأحرف الخاصة**: لا تستخدم أحرفًا خاصة أو مسافات في المسار، أو استخدم علامات اقتباس إذا لزم الأمر ### المشكلة 4: مشاكل مسار قاعدة بيانات SQLite **العرض**: فشل الاتصال عند استخدام SQLite **الحل**: 1. **تحقق من مسار الملف**: تأكد من وجود ملف قاعدة بيانات SQLite وصحة المسار 2. **تحقق من الأذونات**: تأكد من أن ملف قاعدة البيانات لديه أذونات قراءة 3. **عند استخدام Docker**: تأكد من تعيين مسار ملف SQLite بشكل صحيح ## التحديث إلى أحدث إصدار توفر التحديثات المنتظمة ميزات جديدة وإصلاحات أمنية. اختر طريقة التحديث التي تتطابق مع طريقة التثبيت الخاصة بك: ### تحديث الخيار أ (uvx) عندما تقوم بتشغيل MCP Database Utilities باستخدام أمر `uvx` (مثل `uvx mcp-dbutils`)، فإنه يستخدم تلقائيًا أحدث إصدار دون الحاجة إلى تحديثات يدوية. إذا كنت تستخدم طريقة التثبيت التقليدية (ليس أمر `uvx`)، يمكنك التحديث يدويًا باستخدام: ```bash uv pip install -U mcp-dbutils ``` ### تحديث الخيار ب (Docker) 1. احصل على أحدث كود للمشروع: ```bash git pull ``` أو قم بتنزيل أحدث إصدار من [صفحة الإصدارات](https://github.com/donghao1393/mcp-dbutils/releases) 2. أعد بناء صورة Docker الخاصة بك: ```bash docker build -t mcp/dbutils . ``` ### تحديث الخيار ج (Smithery) ```bash npx -y @smithery/cli update @donghao1393/mcp-dbutils ``` ### تحديث الخيار د (بدون اتصال) 1. قم بتنزيل أحدث إصدار من الكود المصدري في بيئة بها وصول إلى الإنترنت 2. استبدل ملفات الكود المصدري في بيئتك غير المتصلة ## أمثلة على التفاعلات بعد التثبيت الناجح، يمكنك تجربة هذه المحادثات النموذجية: **أنت**: هل يمكنك سرد جميع الجداول في قاعدة البيانات الخاصة بي؟ **الذكاء الاصطناعي**: سأتحقق من قاعدة البيانات الخاصة بك. إليك الجداول في قاعدة البيانات الخاصة بك: - العملاء - المنتجات - الطلبات - المخزون **أنت**: ما هو هيكل جدول العملاء؟ **الذكاء الاصطناعي**: جدول العملاء له البنية التالية: - id (عدد صحيح، مفتاح أساسي) - name (نص) - email (نص) - registration_date (تاريخ) - last_purchase (تاريخ) **أنت**: كم عدد العملاء الذين قاموا بعمليات شراء في الشهر الماضي؟ **الذكاء الاصطناعي**: دعني أقوم بتشغيل استعلام لمعرفة ذلك... وفقًا للبيانات، قام 28 عميلًا بعمليات شراء في الشهر الماضي. بلغت القيمة الإجمالية لهذه المشتريات 15,742.50 دولارًا. </div>