مرجع أدوات MCP

يقدم خادم MCP في بروكداك 242 أداة، وتغطي كل ما تفعله في التطبيق تقريبا: البحث في المنافسات، وتسعير البنود، وعروض الأسعار، وطلبات التسعير من الموردين، وأوامر البيع والشراء، والفواتير، والفريق. هذا المرجع يشرح كل أداة: ما تفعله، ومعاملاتها، وما تعيده، ومن يحق له استخدامها.

كيف تعمل الأدوات

كل أداة تقابل إجراء تفعله في التطبيق: ابحث في المنافسات، وسعر بندا، وأنشئ عرض سعر، وسجل عرض مورد. يبدأ اسم الأداة بالمجال ثم الإجراء، مثل tenders_list وquotations_create وrfq_responses_add. وعادة لا تكتب اسم الأداة بنفسك: تطلب من Claude ما تريد بكلامك فيختار الأداة المناسبة ويستدعيها باسمك. وإن كنت تبني عميل MCP خاصا بك فهذه الأسماء والمعاملات هي ما ترسله.

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

من يستطيع استخدام أداة

يلزم لنجاح الاستدعاء ثلاثة أشياء معا، ويذكرها السطر الذي يلي وصف كل أداة:

• الصلاحية (scope): إذن مكتوب على مفتاح API أو على الاتصال، مثل tenders.read أو quotations.write. القراءة والكتابة صلاحيتان منفصلتان، والصلاحية * تمنح كل شيء. والاتصال الذي تنشئه بتسجيل الدخول من Claude يحمل *، ويحده دورك.
• الدور: دورك الحالي في المؤسسة. يقرأ الخادم دورك عند كل استدعاء، فتتغير حدود الاتصال فورا إذا تغير دورك. وبعض الأدوار ترى الأدوات دون الأسعار، وتبين الملاحظات تحت الأداة ذلك.
• الخطة: كل الأدوات للخطة الاحترافية وخطة المؤسسات، فخطة البداية لا تشمل واجهة API ولا ربط MCP، ويرد كل طلب منها 403 plan_upgrade_required مع الميزة api_access. وفي الاحترافية لكل مستخدم مفتاح API واحد أو ربط MCP واحد، ويرفض الثاني بالرمز 403 plan_limit_reached مع api_keys_per_user، ولا حد في خطة المؤسسات.

ويذكر الرفض سببه: 403 مع نص يبدأ بعبارة الصلاحية الناقصة، أو بـinsufficient_role، أو بـplan_upgrade_required، أو بـplan_limit_reached. وتجد تفاصيل كل دور في واجهة البرمجة.

كيف تقرأ وصف أداة

• السطر تحت الوصف: أولا أثر الأداة (للقراءة فقط، أو يغير البيانات، أو يحذف بيانات أو يستبدلها)، ثم الصلاحية، ثم الأدوار، ثم الخطط.
• جدول المعاملات: اسم المعامل ونوعه وهل هو مطلوب ووصفه. الحقول الداخلية تكتب بنقطة، فـitems[].quantity هو حقل quantity في كل عنصر من القائمة items. والأنواع: string وinteger وnumber وboolean وobject، وعلامة [] بعد النوع تعني قائمة منه.
• مثال المعاملات: ما يرسله العميل فعلا، لمن يبني عميلا خاصا به.
• ما يعيده وملاحظات القواعد والحدود التي تفيد قبل الاستدعاء.

قواعد مشتركة

• القوائم تأخذ page (من 1) وpage_size، ويذكر وصف كل أداة حدها الأقصى. والنتيجة الفارغة تعني أن البحث لم يجد شيئا.
• التعديل جزئي: أدوات التعديل تغير ما ترسله فقط، وما لم يرسل يبقى كما هو. وnull يمسح حقلا يقبل الفراغ. والقوائم (مثل بنود منافسة يدوية) لا تستبدل إلا إذا أرسلتها، ويذكر وصف الأداة متى تستبدل بالكامل.
• المعرفات أرقام: معرف المنافسة ومعرف البند ومعرف العرض وهكذا، وتأتي من أدوات القوائم والتفاصيل. وتقاس المبالغ بالريال السعودي ما لم يذكر الوصف غيره.
• التواريخ: last_offer_date هو آخر موعد لتقديم العروض في المنافسة، وsubmission_date تاريخ نشرها. والتاريخ بصيغة YYYY-MM-DD والوقت بصيغة ISO 8601.
• الرفع يكون بترميز base64 داخل JSON في الحقل content_base64، أو بمرجع لملف تحتفظ به المنصة سلفا (staged_ref) فيما تذكر الأداة ذلك. ويرفض الخادم أي طلب يتجاوز نحو 4.5 ميغابايت.
• الحدود: 100 طلب في الدقيقة لكل مفتاح، ويحتسب كل استدعاء من الحد اليومي لمؤسستك: 1,000 في الاحترافية، وبلا حد في المؤسسات.

الملفات والمهام الخلفية

الأداة التي تولد ملفا (PDF أو Excel أو ZIP أو XML) تعيد filename وcontent_type وsize_bytes والمحتوى بترميز base64 في base64. ولا يضمن الملف الذي يتجاوز 4 ميغابايت في الرد، فترد الأداة بخطأ يسمي نقطة REST التي تنزله منها بمفتاحك. وحين يتصل المساعد على واتساب ترسل الملفات إلى المحادثة مستندات بعد الرد.

ويستغرق ملفان أكثر من طلب واحد: ملف مرفقات نوبكو وحزمة ملفات عروض الأسعار. تبنى في الخلفية، وتنتظر الأداة التي تبدأها مدة wait_seconds ثم تعيد الملف أو المهمة، وتتابعها أدوات ملفات العطاء والمهام الخلفية.

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

صفحات المرجع

كل الأدوات أبجديا