MCP-CLI: أداة واجهة سطر الأوامر لبروتوكول سياق النموذج

نظرة عامة على المشروع

MCP-CLI هي أداة واجهة سطر أوامر قوية وغنية بالميزات، مصممة خصيصًا للتفاعل مع خوادم بروتوكول سياق النموذج (Model Context Protocol, MCP). توفر هذه الأداة للمستخدمين قدرة اتصال سلسة مع نماذج اللغة الكبيرة (LLM) من خلال دمج مكتبة بروتوكول CHUK-MCP.

يدعم هذا العميل استخدام الأدوات، وإدارة المحادثات، وأنماط تشغيل متعددة. تم نقل تطبيق البروتوكول الأساسي إلى حزمة مستقلة، مما يسمح لواجهة سطر الأوامر (CLI) بالتركيز على توفير تجربة مستخدم غنية، بينما تتولى مكتبة البروتوكول مسؤولية طبقة الاتصال.

الميزات الأساسية

🔄 أنماط تشغيل متعددة

• وضع الدردشة (Chat Mode): واجهة محادثة تدعم التفاعل المباشر مع نماذج اللغة الكبيرة (LLM) واستخدام الأدوات التلقائي.
• الوضع التفاعلي (Interactive Mode): واجهة موجهة بالأوامر، تُستخدم لعمليات الخادم المباشرة.
• وضع الأوامر (Command Mode): وضع متوافق مع Unix، يدعم الأتمتة النصية وعمليات الأنابيب (piping).
• الأوامر المباشرة: لتشغيل أمر واحد دون الحاجة للدخول إلى الوضع التفاعلي.

🌐 دعم مزودين متعددين

• تكامل OpenAI: يدعم نماذج مثل gpt-4o-mini، gpt-4o، gpt-4-turbo، وغيرها.
• تكامل Ollama: يدعم النماذج المحلية مثل llama3.2، qwen2.5-coder، وغيرها.
• هندسة معمارية قابلة للتوسيع: تدعم إضافة مزودين آخرين.

🛠️ نظام أدوات قوي

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

💬 إدارة محادثات متقدمة

• تتبع كامل لسجل المحادثات.
• يدعم تصفية وعرض نطاقات رسائل محددة.
• وظيفة تصدير JSON، لتصحيح الأخطاء أو التحليل.
• وظيفة ضغط المحادثات، لتقليل استخدام الرموز (tokens).

🎨 تجربة مستخدم غنية

• إكمال تلقائي للأوامر حساس للسياق.
• إخراج وحدة التحكم المنسق بالألوان.
• مؤشر تقدم للعمليات طويلة الأمد.
• مساعدة ووثائق مفصلة.

🔧 إدارة موارد موثوقة

• تنظيف مناسب لموارد الإدخال/الإخراج غير المتزامن (Asynchronous IO).
• معالجة أخطاء أنيقة.
• استعادة نظيفة للطرفية.
• يدعم اتصالات خادم متعددة ومتزامنة.

متطلبات النظام

• Python 3.11 أو إصدار أحدث.
• بالنسبة لـ OpenAI: يجب تعيين مفتاح API صالح في متغير البيئة OPENAI_API_KEY.
• بالنسبة لـ Ollama: يتطلب تثبيت Ollama محليًا.
• ملف تكوين الخادم (افتراضي: server_config.json).
• مكتبة بروتوكول CHUK-MCP.

طرق التثبيت

التثبيت القياسي

# استنساخ المستودع
git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli

# تثبيت الحزمة وتوابع التطوير
pip install -e ".[cli,dev]"

# تشغيل واجهة سطر الأوامر (CLI)
mcp-cli --help

استخدام UV لإدارة التوابع

# تثبيت UV (إذا لم يكن مثبتًا)
pip install uv

# تثبيت التوابع
uv sync --reinstall

# التشغيل باستخدام UV
uv run mcp-cli --help

دليل الاستخدام

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

تدعم جميع الأوامر الخيارات العامة التالية:

• --server: لتحديد الخادم المراد الاتصال به (افصل بين الخوادم المتعددة بفاصلة).
• --config-file: مسار ملف تكوين الخادم (افتراضي: server_config.json).
• --provider: مزود LLM المستخدم (openai أو ollama، افتراضي: openai).
• --model: النموذج المحدد المستخدم (يعتمد على القيم الافتراضية للمزود).
• --disable-filesystem: لتعطيل الوصول إلى نظام الملفات (افتراضي: true).

وضع الدردشة

يوفر وضع الدردشة واجهة محادثة مع LLM، ويستخدم الأدوات المتاحة تلقائيًا عند الحاجة:

# وضع الدردشة الأساسي
mcp-cli chat --server sqlite

# تحديد المزود والنموذج
mcp-cli chat --server sqlite --provider openai --model gpt-4o
mcp-cli chat --server sqlite --provider ollama --model llama3.2

أوامر الشرطة المائلة في وضع الدردشة

في وضع الدردشة، يمكن استخدام أوامر الشرطة المائلة التالية:

أوامر المساعدة:

• /help: لعرض الأوامر المتاحة.
• /help <command>: لعرض مساعدة مفصلة لأمر معين.
• /quickhelp أو /qh: لعرض مرجع سريع للأوامر الشائعة.

متعلقة بالأدوات:

• /tools: لعرض جميع الأدوات المتاحة ومعلومات الخادم الخاصة بها.
• /tools --all: لعرض معلومات مفصلة عن الأدوات بما في ذلك المعلمات.
• /tools --raw: لعرض تعريفات الأدوات الخام.
• /toolhistory أو /th: لعرض سجل استدعاء الأدوات في الجلسة الحالية.

إدارة المحادثات:

• /conversation أو /ch: لعرض سجل المحادثات.
• /save <filename>: لحفظ سجل المحادثات في ملف JSON.
• /compact: لضغط سجل المحادثات إلى ملخص.

التحكم في الواجهة:

• /cls: لمسح الشاشة مع الاحتفاظ بسجل المحادثات.
• /clear: لمسح الشاشة وسجل المحادثات.
• /verbose أو /v: لتبديل وضع عرض الأدوات بين المفصل والموجز.

الوضع التفاعلي

يوفر الوضع التفاعلي واجهة سطر أوامر، باستخدام أوامر الشرطة المائلة للتفاعل المباشر مع الخادم:

mcp-cli interactive --server sqlite

أوامر الوضع التفاعلي

• /ping: للتحقق مما إذا كان الخادم يستجيب.
• /prompts: لسرد المطالبات المتاحة.
• /tools: لسرد الأدوات المتاحة.
• /resources: لسرد الموارد المتاحة.
• /chat: للدخول إلى وضع الدردشة.
• /exit أو /quit: للخروج من البرنامج.

وضع الأوامر

يوفر وضع الأوامر واجهة متوافقة مع Unix، للأتمتة وتكامل الأنابيب:

mcp-cli cmd --server sqlite [options]

خيارات وضع الأوامر

• --input: مسار ملف الإدخال (استخدم - للإشارة إلى stdin).
• --output: مسار ملف الإخراج (استخدم - للإشارة إلى stdout، افتراضي).
• --prompt: قالب المطالبة (استخدم {{input}} كعنصر نائب للإدخال).
• --raw: لإخراج النص الخام بدون تنسيق.
• --tool: لاستدعاء أداة معينة مباشرة.
• --tool-args: معلمات JSON لاستدعاء الأداة.
• --system-prompt: مطالبة نظام مخصصة.

أمثلة وضع الأوامر

# تلخيص مستند
mcp-cli cmd --server sqlite --input document.md --prompt "Summarize this: {{input}}" --output summary.md

# معالجة stdin والإخراج إلى stdout
cat document.md | mcp-cli cmd --server sqlite --input - --prompt "Extract key points: {{input}}"

# استدعاء أداة مباشرة
mcp-cli cmd --server sqlite --tool list_tables --raw
mcp-cli cmd --server sqlite --tool read_query --tool-args '{"query": "SELECT COUNT(*) FROM users"}'

# معالجة الدفعات
ls *.md | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary.md --prompt "Summarize: {{input}}"

الأوامر المباشرة

لتشغيل أمر واحد دون الحاجة للدخول إلى الوضع التفاعلي:

# سرد الأدوات المتاحة
mcp-cli tools list --server sqlite

# استدعاء أداة معينة
mcp-cli tools call --server sqlite

# سرد المطالبات المتاحة
mcp-cli prompts list --server sqlite

# التحقق من اتصال الخادم
mcp-cli ping --server sqlite

# سرد الموارد المتاحة
mcp-cli resources list --server sqlite

ملف التكوين

أنشئ ملف server_config.json لتكوين الخوادم:

{
  "mcpServers": {
    "sqlite": {
      "command": "python",
      "args": ["-m", "mcp_server.sqlite_server"],
      "env": {
        "DATABASE_PATH": "your_database.db"
      }
    },
    "another-server": {
      "command": "python",
      "args": ["-m", "another_server_module"],
      "env": {}
    }
  }
}

هيكل المشروع

src/
├── mcp_cli/
│   ├── chat/                    # تطبيق وضع الدردشة
│   │   ├── commands/            # أوامر الشرطة المائلة للدردشة
│   │   │   ├── __init__.py      # نظام تسجيل الأوامر
│   │   │   ├── conversation.py  # إدارة المحادثات
│   │   │   ├── help.py          # أوامر المساعدة
│   │   │   ├── tools.py         # أوامر الأدوات
│   │   │   └── ...
│   │   ├── chat_context.py      # إدارة حالة جلسة الدردشة
│   │   ├── chat_handler.py      # معالج حلقة الدردشة الرئيسية
│   │   ├── command_completer.py # الإكمال التلقائي للأوامر
│   │   └── ui_manager.py        # واجهة المستخدم
│   ├── commands/                # أوامر CLI
│   │   ├── chat.py              # أمر الدردشة
│   │   ├── cmd.py               # وضع الأوامر
│   │   ├── interactive.py       # الوضع التفاعلي
│   │   └── ...
│   ├── llm/                     # تطبيق عميل LLM
│   │   ├── providers/           # عملاء خاصون بالمزودين
│   │   │   ├── base.py          # عميل LLM الأساسي
│   │   │   └── openai_client.py # تطبيق OpenAI
│   │   └── llm_client.py        # مصنع العملاء
│   ├── ui/                      # مكونات واجهة المستخدم
│   │   ├── colors.py            # تعريفات الألوان
│   │   └── ui_helpers.py        # أدوات واجهة المستخدم
│   ├── main.py                  # نقطة الدخول الرئيسية
│   └── config.py                # محمل التكوين

أمثلة الاستخدام

التنفيذ التلقائي للأدوات

في وضع الدردشة، يمكن لـ MCP CLI تنفيذ الأدوات التي يوفرها الخادم تلقائيًا:

You: What tables are available in the database?
Assistant: Let me check for you.
[Tool Call: list_tables]
I found the following tables in the database:
- users
- products  
- orders
- categories

You: How many users do we have?
Assistant: I'll query the database for that information.
[Tool Call: read_query]
There are 873 users in the database.

نصوص الأتمتة

يدعم وضع الأوامر نصوص أتمتة قوية:

#!/bin/bash
# مثال على نص برمجي لتحليل مستندات متعددة

# معالجة جميع ملفات markdown في الدليل الحالي
for file in *.md; do
    echo "Processing $file..."
    
    # إنشاء ملخص
    mcp-cli cmd --server sqlite --input "$file" \
        --prompt "Summarize this document: {{input}}" \
        --output "${file%.md}.summary.md"
    
    # استخراج الكيانات
    mcp-cli cmd --server sqlite --input "$file" \
        --prompt "Extract all company names, people, and locations from this text: {{input}}" \
        --output "${file%.md}.entities.txt" --raw
done

# إنشاء تقرير شامل
echo "Creating final report..."
cat *.entities.txt | mcp-cli cmd --server sqlite --input - \
    --prompt "Analyze these entities and identify the most frequently mentioned:" \
    --output report.md

إدارة سجل المحادثات

تتبع وإدارة سجل المحادثات:

> /conversation
Conversation History (12 messages)
# | Role | Content
1 | system | You are an intelligent assistant capable of using t...
2 | user | What tables are available in the database?
3 | assistant | Let me check for you.
4 | assistant | [Tool call: list_tables]
...

> /conversation 4
Message #4 (Role: assistant)
[Tool call: list_tables]
Tool Calls:
1. ID: call_list_tables_12345678, Type: function, Name: list_tables
Arguments: {}

> /save conversation.json
Conversation saved to conversation.json

> /compact
Conversation history compacted with summary.
Summary:
The user asked about database tables, and I listed the available tables (users, products, orders, categories). The user then asked about the number of users, and I queried the database to find there are 873 users.

إدارة التوابع

تستخدم واجهة سطر الأوامر (CLI) مجموعات توابع اختيارية للتنظيم:

• cli: واجهة مستخدم طرفية غنية، إكمال تلقائي للأوامر، وتكامل المزودين.
• dev: أدوات التطوير وأدوات الاختبار.
• wasm: (محجوز لدعم WebAssembly المستقبلي).
• chuk-mcp: مكتبة تطبيق البروتوكول (التابع الأساسي).

لتثبيت الإضافات المحددة:

pip install "mcp-cli[cli]"        # وظائف CLI الأساسية
pip install "mcp-cli[cli,dev]"    # CLI + أدوات التطوير

دليل المساهمة

نرحب بالمساهمات! يرجى اتباع الخطوات التالية:

1. انسخ المستودع (Fork the repository).
2. أنشئ فرعًا للميزة (git checkout -b feature/amazing-feature).
3. قم بتثبيت التغييرات (git commit -m 'Add some amazing feature').
4. ادفع إلى الفرع (git push origin feature/amazing-feature).
5. افتح طلب سحب (Pull Request).

حول بروتوكول سياق النموذج (MCP)

MCP هو بروتوكول مفتوح يوحد طريقة توفير التطبيقات للسياق لنماذج اللغة الكبيرة (LLM). يمكن تشبيه MCP بمنفذ USB-C لتطبيقات الذكاء الاصطناعي. فكما يوفر USB-C طريقة موحدة لربط الأجهزة بمختلف الأجهزة الطرفية والملحقات، يوفر MCP طريقة موحدة لربط نماذج الذكاء الاصطناعي بمصادر البيانات والأدوات المتنوعة.