خادم MCP

يعرض CodFlow خادمًا بعيدًا لـ Model Context Protocol باسم CodFlow CRM. يمكن لعملاء الذكاء الاصطناعي سرد طلبات المتجر وعملائه ومنتجاته وشحناته، وتنفيذ إجراءات كتابة بالصلاحيات نفسها التي يملكها مستخدم لوحة التحكم المسجّل.

يمكن الوصول إلى الخادم على:

البيئة	URL
الإنتاج	`https://api.codflow.store/mcp`
محلي	`http://localhost:8787/mcp`

نقطة النهاية محمية بـ OAuth. لا يستطيع العميل استدعاء أداة دون رمز وصول صالح، ويحمل الرمز نطاقات CodFlow الخاصة بالمستخدم.

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

يستخدم خادم MCP نموذج المورد المحمي في OAuth 2.1:

ينشر الخادم بيانات المورد المحمي وخادم التفويض في المسارات القياسية (well-known) الخاصة بـ OAuth.
يكتشف العملاء المستندين تلقائيًا من نقطة نهاية MCP.
يدعم الخادم تسجيل العملاء الديناميكي على /oauth/register ومستندات Client ID Metadata.
نقطة نهاية التفويض هي /authorize؛ وتُصدر الرموز على /oauth/token.
رموز الوصول تدوم ساعة واحدة؛ ورموز التحديث تدوم 30 يومًا.

عندما يتصل عميل، يفتح شاشة موافقة CodFlow. سجّل الدخول بحساب لوحة التحكم الذي يجب أن يستخدم الوكيل بياناته وصلاحياته. تعرض الشاشة النطاقات المطلوبة، ولا يمنح الخادم إلا النطاقات التي يملكها المستخدم فعلًا. ويمكن للمسؤول منح أي نطاق مطلوب.

يستنتج الخادم مورد OAuth من WORKER_SELF_URL. للاختبار المحلي، تأكد من أن القيمة تطابق الأصل الذي يستخدمه عميلك (http://localhost:8787).

ربط عميل

افتح إعدادات MCP أو الموصل في عميلك

أضف خادم MCP بعيدًا. استخدم عنوان الإنتاج، أو العنوان المحلي أثناء التطوير.
ابدأ الاتصال

يكتشف العميل بيانات OAuth ويفتح شاشة تسجيل الدخول والموافقة في CodFlow.
وافق على النطاقات

سجّل الدخول بالحساب الذي يجب أن يعمل الوكيل باسمه. راجع النطاقات. لن يمنح الخادم أكثر مما يملكه الحساب بالفعل.
اسرد الأدوات

بعد اكتمال الاستدعاء الراجع، اطلب من العميل سرد أدوات CodFlow. تُسجَّل فقط الأدوات المسموح بها وفق نطاقات الرمز، لذا لا يرى النموذج أبدًا أداة لا يستطيع استدعاءها.

إعداد العميل

{
  "mcpServers": {
    "codflow": {
      "url": "https://api.codflow.store/mcp"
    }
  }
}

استخدم الشكل نفسه مع http://localhost:8787/mcp لخادم محلي. يختلف مسار الإعدادات الدقيق حسب العميل؛ أما عنوان URL وتدفق OAuth فهما متطابقان.

الأدوات

تُجمَّع الأدوات حسب المجال وتُقيَّد بالنطاقات نفسها المطبقة في REST API. بعض الأمثلة:

المجال	أدوات مثال
العملاء	`listCustomers`، `getCustomerDetails`، `findCustomerByPhone`، `getCustomerOrderHistory`
المنتجات	`listProducts`، `getProductDetails`، `createNewProduct`، `updateProductDetails`
الطلبات	`listOrders`، `getOrderDetails`، `createOrder`، `updateOrderStatus`
الشحنات	`getShipment`، `handOffOrderToCarrier`، `reportShipmentEvent`
التوصيل	السائقون، مدفوعات السائقين، شركات التوصيل، ملفات الشحن
الكتالوج	المتغيرات، مجموعات المنتجات، المخزون، العروض، الكوبونات
واجهة المتجر	صفحات الهبوط، المراجعات، مجموعات العملاء، وسوم العملاء
المرجع	الولايات والبلديات

لكل أداة مخطط إدخال مُعرّف الأنواع، ومخطط إخراج عندما تعيد بيانات منظمة. ويتلقى العميل عناوين مقروءة وتعليقات أمان مع تعريف الأداة.

الصلاحيات والأمان

تقييد وقت التسجيل. لا تُسجَّل الأداة إلا إذا كان الرمز يملك النطاق المطلوب. ولا يستطيع النموذج اكتشاف أو استدعاء أداة خارج صلاحيات المستخدم.
تجاوز المسؤول. يمكن لرمز المسؤول منح كل النطاقات؛ أما رمز موظف الطاقم فيمنح فقط النطاقات التي يملكها الموظف.
تعليقات الإجراءات المدمّرة. تُوسم عمليات الحذف وتعديل المخزون وتغيير حالة الطلب والتسويات وتسليم الطلبات لشركات التوصيل بـ destructiveHint: true. ويجب على عملاء MCP الذين يدعمون التأكيد طلب الموافقة قبل تنفيذها؛ راجع إعدادات التأكيد في عميلك.
مسار التدقيق. تُسجَّل استدعاءات الأدوات عبر MCP في سجل النشاط باسم المستخدم المسجّل.
تحديد المعدل. تخضع استدعاءات الأدوات لتحديد المعدل لكل مستخدم أو لكل موضوع عميل.
الإبطال. أبطلِ الاتصال من MCP في لوحة التحكم. تقع API الإدارة الأساسية تحت /api/mcp:
- GET /api/mcp/me — اتصالاتك
- DELETE /api/mcp/connections/{clientId} — إبطال اتصالك
- GET /api/mcp/team — اتصالات الفريق (مسؤول)
- DELETE /api/mcp/connections/{clientId}/users/{userId} — إبطال اتصال مستخدم (مسؤول)

استكشاف الأخطاء

لا تظهر أدوات. قد لا يملك الرمز أي نطاقات، أو قد لا يشمل دور المستخدم أي مجال أدوات. أعد الاتصال ووافق على نطاق واحد على الأقل.
401 مع تحدّي WWW-Authenticate. لا يملك العميل رمزًا صالحًا. دعه يعيد تشغيل تدفق OAuth؛ ولا تلصق مفتاح API من لوحة التحكم في عنوان MCP.
403 عند استدعاء أداة. نطاقات الرمز لا تغطي تلك الأداة، أو أصبح الحساب غير نشط. تحقق من المستخدم في لوحة التحكم.
عميل محلي لا يكمل OAuth. تأكد من أن WORKER_SELF_URL يطابق العنوان الذي ضبطته، ومن أن العميل يستطيع الوصول إلى http://localhost:8787.

خادم MCP منفصل عن REST API. ولا يظهر كعمليات في مرجع API؛ استخدم هذا الدليل لمعرفة نقطة نهايته وسلوك OAuth.

Webhooks شركات التوصيل البنية