بوابة MCP (بروتوكول سياق النموذج) ومركز تسجيل غني بالميزات، يوفر إدارة موحدة للأدوات والموارد والتلميحات، ويدعم تحويل REST API إلى بروتوكول MCP، مع إمكانات الأمان والمراقبة.

مشروع MCP Context Forge: وصف تفصيلي

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

MCP Context Forge هو بوابة بروتوكول سياق النموذج (MCP) غنية بالميزات ومدفوعة بـ FastAPI مفتوحة المصدر من IBM، وهي توحد وتدمج الأدوات والموارد والمطالبات والخوادم والبوابات النظيرة، وتغلف أي واجهة برمجة تطبيقات REST كأداة متوافقة مع معايير MCP أو خادم افتراضي. يدعم المشروع عرض جميع الوظائف من خلال بروتوكولات نقل HTTP/JSON-RPC و WebSocket وأحداث إرسال الخادم (SSE) و stdio، ويوفر واجهة مستخدم إدارية تفاعلية غنية، معبأة في شكل حاوية، ويدعم أي قاعدة بيانات مدعومة من SQLAlchemy.

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

1. وظائف بوابة البروتوكول

• هندسة بوابة حقيقية: مركزية لتسجيل الأدوات والموارد والمطالبات، مع الحفاظ على معيار بروتوكول MCP 2025-03-26 الرسمي.
• اتحاد متعدد الخوادم: توحيد خوادم MCP متعددة في نقطة نهاية واحدة - اكتشاف تلقائي للعقد النظيرة (mDNS أو تكوين صريح)، وفحوصات السلامة ودمج وظائفها.
• خدمات افتراضية: تحويل الخدمات غير MCP إلى "خوادم افتراضية"، حيث يمكن تسجيل أي واجهة برمجة تطبيقات REST أو نقطة نهاية وظيفة وعرضها ضمن دلالات MCP.

2. وظائف تكييف واجهة برمجة التطبيقات

• محول REST إلى MCP: تكييف أي واجهة برمجة تطبيقات REST/HTTP كأداة MCP، مع دعم التحقق من صحة إدخال JSON-Schema، وسياسات إعادة المحاولة/تحديد المعدل واستدعاء JSON-RPC الشفاف.
• تحويل البروتوكول: دعم التحويل بين بروتوكولات نقل متعددة (stdio، SSE، HTTP قابل للتدفق).

3. النشر والإدارة

• واجهة مستخدم إدارية كاملة: توفير بروتوكولات نقل غنية، وخطوط أنابيب تجربة تطوير مبنية مسبقًا وقابلية ملاحظة على مستوى الإنتاج.
• وظائف على مستوى المؤسسات: تتضمن مصادقة وتخويل، والتخزين المؤقت، وفحوصات السلامة، وجمع المقاييس ووظائف كاملة أخرى.

هيكل النظام

يعتمد المشروع تصميمًا معماريًا معياريًا:

┌─────────────────┐    ┌──────────────────┐
│  🖥️ Admin UI    │    │  🔐 المصادقة والتخويل      │
│  واجهة الإدارة        │    │  JWT + Basic     │
└─────────────────┘    └──────────────────┘
         │                        │
         └────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │        🚪 جوهر بوابة MCP        │
    │     اكتمل تهيئة البروتوكول Ping      │
    │        مدير الاتحاد              │
    │   بروتوكولات النقل HTTP WS SSE Stdio  │
    └─────────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │           طبقة الخدمة               │
    │  🧰 خدمة الأدوات  📁 خدمة الموارد      │
    │  📝 خدمة المطالبات  🧩 خدمة الخوادم    │
    └─────────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │          طبقة الثبات              │
    │    💾 قاعدة البيانات SQLAlchemy       │
    │    ⚡ التخزين المؤقت Redis/Memory       │
    └───────────────────────────────┘

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

البروتوكولات والنقل المدعومة

• دعم كامل لـ MCP 2025-03-26: initialize، ping، notify، completion، sampling (SSE)، بالإضافة إلى التراجع JSON-RPC.
• بروتوكولات نقل متعددة: HTTP/JSON-RPC، WebSocket (ping/pong)، SSE (أحادي الاتجاه + قناة الإرجاع)، stdio.
• تحويل البروتوكول: دعم التحويل السلس بين بروتوكولات النقل المختلفة.

الاتحاد والاكتشاف

• الاكتشاف التلقائي: دعم اكتشاف البوابة النظيرة mDNS أو التكوين الصريح.
• فحوصات السلامة: فحوصات سلامة دورية، تدعم تجاوز الفشل.
• دمج شفاف: دمج السجلات البعيدة بشفافية في دليل موحد.

إدارة الموارد

• URI القابلة للقولبة: دعم URI للموارد ذات المعلمات.
• التخزين المؤقت الذكي: آلية التخزين المؤقت LRU+TTL، واكتشاف نوع MIME.
• الاشتراك في الوقت الفعلي: دعم الاشتراك في الوقت الفعلي في تغييرات الموارد عبر SSE.

إدارة المطالبات

• قوالب Jinja2: دعم محرك القوالب القوي.
• التحقق من صحة المخطط: التحقق الإلزامي من صحة JSON-Schema.
• دعم متعدد الوسائط: دعم كتل المحتوى متعددة الوسائط.
• التحكم في الإصدار: إدارة الإصدارات ووظائف التراجع.

إدارة الأدوات

• دعم أنواع متعددة: MCP أصلي أو أدوات قائمة على REST.
• التحقق من صحة الإدخال: آلية كاملة للتحقق من صحة الإدخال.
• منطق إعادة المحاولة: إعادة محاولة ذكية وتحديد المعدل/التحكم المتزامن.

وظائف الإدارة والمراقبة

واجهة إدارة الويب

• المكدس التقني: HTMX + Alpine.js + Tailwind CSS
• CRUD كامل: إدارة كاملة للخوادم والأدوات والموارد والمطالبات والبوابات والجذر والمقاييس.
• المراقبة في الوقت الفعلي: مراقبة الحالة في الوقت الفعلي وعرض السجلات.

المصادقة والتخويل

• طرق مصادقة متعددة: مصادقة Basic، و JWT Bearer، ومصادقة رأس مخصصة.
• تحكم دقيق: التحكم في حقن التبعية لكل نقطة نهاية.
• تشفير آمن: تخزين مشفر AES لرؤوس مصادقة الأدوات.

الثبات والترحيل

• دعم ORM: SQLAlchemy ORM غير متزامن (SQLite، PostgreSQL، MySQL، إلخ).
• الترحيل التلقائي: ترحيل قاعدة بيانات Alembic التلقائي.
• تجمع الاتصال: تكوين كامل لتجمع اتصالات قاعدة البيانات.

نظام الأحداث وقابلية الملاحظة

• أحداث موحدة: تغليف أحداث موحد لـ WS/SSE.
• تصفية من جانب الخادم: تصفية الأحداث من جانب الخادم وخطافات الإرجاع.
• تسجيل منظم: تسجيل JSON منظم.
• فحوصات السلامة: نقطة نهاية /health وزخرفة مقاييس التأخير.
• مقاييس كاملة: جمع المقاييس لكل معالج.

تجربة التطوير

أدوات التطوير

• أهداف Makefile: أكثر من 100 هدف تطوير محدد مسبقًا.
• جودة التعليمات البرمجية: خطافات ما قبل الالتزام (ruff، black، mypy، isort).
• إعادة التحميل في الوقت الفعلي: يدعم خادم التطوير إعادة التحميل في الوقت الفعلي.
• تغطية الاختبار: أكثر من 400 حالة اختبار.
• CI/CD: شارات CI كاملة وعمليات آلية.

خيارات النشر

• النشر في حاويات: دعم Docker/Podman.
• Cloud Native: دعم نشر IBM Cloud Code Engine.
• بيئات متعددة: تكوين بيئات التطوير والاختبار والإنتاج.
• SSL/TLS: دعم كامل لـ HTTPS.

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

التكوين الأساسي

# التكوين الأساسي للتطبيق
APP_NAME=MCP Gateway
HOST=0.0.0.0
PORT=4444
DATABASE_URL=sqlite:///./mcp.db
APP_ROOT_PATH=/gateway  # بادئة مسار فرعي اختيارية

تكوين المصادقة

# مصادقة Basic (واجهة الإدارة و API)
BASIC_AUTH_USER=admin
BASIC_AUTH_PASSWORD=changeme

# تكوين JWT
JWT_SECRET_KEY=my-test-key
JWT_ALGORITHM=HS256
TOKEN_EXPIRY=10080  # دقائق

# التحكم في المصادقة
AUTH_REQUIRED=true
AUTH_ENCRYPTION_SECRET=my-test-salt

تكوين الاتحاد

# وظيفة الاتحاد
FEDERATION_ENABLED=true
FEDERATION_DISCOVERY=false
FEDERATION_PEERS=["http://peer1:4444","http://peer2:4444"]
FEDERATION_TIMEOUT=30
FEDERATION_SYNC_INTERVAL=300

بداية سريعة

التشغيل باستخدام Docker

docker run -d --name mcpgateway \
  -p 4444:4444 \
  -e HOST=0.0.0.0 \
  -e JWT_SECRET_KEY=my-secret-key \
  -e BASIC_AUTH_USER=admin \
  -e BASIC_AUTH_PASSWORD=changeme \
  -e AUTH_REQUIRED=true \
  -e DATABASE_URL=sqlite:///./mcp.db \
  ghcr.io/ibm/mcp-context-forge:latest

التطوير المحلي

# إنشاء بيئة افتراضية وتثبيت التبعيات
make venv install serve

# أو التثبيت يدويًا
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
uvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444

إنشاء رمز مصادقة

export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 10080 --secret my-test-key)

أمثلة على استخدام API

تهيئة البروتوكول

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "protocol_version":"2025-03-26",
    "capabilities":{},
    "client_info":{"name":"MyClient","version":"1.0.0"}
  }' \
  http://localhost:4444/protocol/initialize

تسجيل أداة

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "name":"clock_tool",
    "url":"http://localhost:9000/rpc",
    "description":"Returns current time",
    "input_schema":{
      "type":"object",
      "properties":{"timezone":{"type":"string"}},
      "required":[]
    }
  }' \
  http://localhost:4444/tools

إنشاء قالب مطالبة

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "name":"greet",
    "template":"Hello, {{ user }}!",
    "argument_schema":{
      "type":"object",
      "properties":{"user":{"type":"string"}},
      "required":["user"]
    }
  }' \
  http://localhost:4444/prompts

النشر إلى IBM Cloud Code Engine

يوفر المشروع دعمًا كاملاً لنشر IBM Cloud Code Engine:

تكوين البيئة

IBMCLOUD_REGION=us-south
IBMCLOUD_RESOURCE_GROUP=default
IBMCLOUD_PROJECT=my-codeengine-project
IBMCLOUD_CODE_ENGINE_APP=mcpgateway
IBMCLOUD_IMAGE_NAME=us.icr.io/myspace/mcpgateway:latest
IBMCLOUD_API_KEY=your_api_key_here

أوامر النشر

make ibmcloud-check-env      # التحقق من متغيرات البيئة
make ibmcloud-cli-install    # تثبيت IBM Cloud CLI
make ibmcloud-login          # تسجيل الدخول إلى IBM Cloud
make ibmcloud-ce-login       # تحديد مشروع Code Engine
make ibmcloud-tag            # وضع علامة على صورة الحاوية
make ibmcloud-push           # الدفع إلى IBM Container Registry
make ibmcloud-deploy         # النشر إلى Code Engine

هيكل المشروع

mcpgateway/
├── admin.py                    # مسارات FastAPI ووحدة التحكم في واجهة الإدارة
├── cache/
│   └── resource_cache.py      # ذاكرة التخزين المؤقت LRU+TTL للموارد
├── config.py                  # محمل إعدادات Pydantic
├── db.py                      # نماذج SQLAlchemy ORM وإعدادات قاعدة البيانات
├── federation/
│   ├── discovery.py           # اكتشاف البوابة النظيرة
│   ├── forward.py             # منطق إعادة توجيه RPC
│   └── manager.py             # تنسيق الاتحاد وفحوصات السلامة
├── handlers/
│   └── sampling.py            # معالج طلبات أخذ العينات المتدفقة MCP
├── services/
│   ├── completion_service.py  # منطق إكمال معلمات المطالبات والموارد
│   ├── gateway_service.py     # تسجيل وإدارة البوابة النظيرة
│   ├── prompt_service.py      # CRUD قالب المطالبة والعرض
│   ├── resource_service.py    # تسجيل الموارد واسترجاعها والاشتراك فيها
│   ├── server_service.py      # تسجيل الخادم ومراقبة السلامة
│   └── tool_service.py        # تسجيل الأدوات واستدعائها ومقاييسها
├── transports/
│   ├── sse_transport.py       # نقل أحداث إرسال الخادم
│   ├── stdio_transport.py     # نقل stdio
│   └── websocket_transport.py # نقل WebSocket
└── utils/
    ├── create_jwt_token.py    # أداة إنشاء وفحص JWT
    └── verify_credentials.py # تبعية مصادقة FastAPI

التطوير والمساهمة

إعداد بيئة التطوير

# تثبيت تبعيات التطوير
make install-dev

# تشغيل فحص التعليمات البرمجية
make lint

# تشغيل الاختبارات
make test

# تشغيل اختبار التغطية
make coverage

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

يدمج المشروع العديد من أدوات جودة التعليمات البرمجية:

• التنسيق: black، isort، autoflake
• التحليل الثابت: mypy، pylint، pyright، pyre
• الفحص الأمني: bandit، pip-audit
• تحليل التعقيد: radon، wily
• فحص التبعية: fawltydeps، pip-licenses

ملخص

MCP Context Forge هو حل بوابة بروتوكول سياق نموذج كامل الميزات وجاهز للإنتاج، وهو مناسب بشكل خاص لدمج الأدوات وإدارة تطبيقات LLM على مستوى المؤسسات. لا يحقق فقط الوظائف الكاملة لبروتوكول MCP، ولكنه يوفر أيضًا وظائف توسيع غنية، مثل اكتشاف الاتحاد، وتحويل البروتوكول، والخدمات الافتراضية، وما إلى ذلك، وهو مكون البنية التحتية المثالي لبناء نظام بيئي معقد لتطبيقات الذكاء الاصطناعي.