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

توفر Nordlet بروتوكول سياق النموذج (Model Context Protocol) على العنوان https://api.nordlet.com/mcp. يمكن لمساعد ذكي متصل بهذا البروتوكول البحث في واجهة برمجة التطبيقات، وقراءة مخطط الطلب (request schema) لأي عملية واستدعاؤها باستخدام نفس مفتاح واجهة برمجة التطبيقات والشركة والصلاحيات (scopes) كما لو كان طلباً مباشراً. يعد كل استدعاء لأداة طلباً عادية لواجهة برمجة التطبيقات، إذ يتم التحقق من هويته وتطبيق حدود المعدل (rate limits) واحتساب تكلفته بالطريقة نفسها، كما أن أي عملية تعديل تؤدي إلى تغيير الدفاتر المحاسبية للشركة.

الاتصال

يدعم نقطة النهاية (endpoint) بروتوكول HTTP القابل للبث (Streamable HTTP)، ويتم المصادقة عليها باستخدام مفتاح واجهة برمجة التطبيقات المرفق بصيغة حامل (Bearer) من قسم البدء (Getting started). في بيئة Claude Code:

claude mcp add --transport http nordlet https://api.nordlet.com/mcp --header "Authorization: Bearer nl_..."

يقبل أي عميل بروتوكول سياق نموذج (MCP client) آخر نفس الرابط ورأس الطلب. يمكن لمفتاح محدود الصلاحيات بالنطاق *:read استدعاء عمليات القراءة فقط، حيث تُبلغ الأدوات عن نقص الصلاحيات في صورة خطأ 403 صادر عن واجهة برمجة التطبيقات.

الأدوات

تغطي ثلاث أدوات كل عملية في واجهة برمجة التطبيقات:

الأداة	الوظيفة
search_operations	تبحث عن العمليات باستخدام كلمات من اسم العملية أو مسارها أو ملخصها أو وصفها، مع إمكانية التخصيص ضمن وحدة معينة (sales للمبيعات، bank للبنوك، reports للتقارير، ...). في حال عدم إدخال استعلام، تعرض الأداة قائمة الوحدات المتاحة.
describe_operation	تعيد طريقة الطلب (method) والمسار والوصف ومخطط طلب JSON الخاص بعملية واحدة؛ ويؤدي استخدام الخيار includeResponse: true إلى إضافة مخطط استجابة 200.
call_operation	تنفذ عملية واحدة مع تمرير جسم طلب بصيغة JSON. يعود جسم الاستجابة بصيغة JSON، بينما يعود استجابة خطأ من الفئة 4xx أو 5xx في صورة خطأ أداة يتضمن رمز الحالة وهيكل الخطأ (error envelope). يتم إرسال مفتاح عدم التكرار الاختياري idempotencyKey عبر رأس الطلب Idempotency-Key، بحيث يؤدي تكرار الاستدعاء بنفس المفتاح إلى إعادة الاستجابة الأولى بدلاً من تكرار أثر العملية.

تتوفر العمليات الأكثر استخداماً أيضاً في صورة أدوات مباشرة مع مخططات طلباتها الخاصة، مما يتيح للمساعد رؤية حقولها دون الحاجة لعملية بحث مسبقة: partners_list، partners_get، partners_create، partners_find_or_create، catalog_items_list، sales_invoices_list، sales_invoices_get، sales_invoices_create، sales_invoices_issue، sales_invoices_send، purchases_invoices_list، purchases_invoices_create، purchases_invoices_register، bank_transactions_list، bank_transactions_import، bank_transactions_match، ledger_journal_transactions_list، reports_trial_balance، reports_financial_statements، reports_vat_summary و reports_debt_aging. تحمل كل أداة تعلي توضيحية خاصة ببروتوكول سياق النموذج (readOnlyHint، destructiveHint) والتي توضح للعميل ما إذا كانت الأداة تقوم بعملية كتابة.

يتم توليد فهرس العمليات والمخططات من نفس وصف OpenAPI المستخدم في مرجع واجهة برمجة التطبيقات (API reference) وحزم تطوير الصانع (SDKs)، وعليه فإن أي عملية تتم إضافتها إلى واجهة برمجة التطبيقات تظهر تلقائياً في search_operations مع الإصدار الذي أضافها. تذكّر توجيهات الخادم المساعد بالمعايير المتبعة: المبالغ المالية تُمثل كسلاسل نصية عشرية، والقوائم تقبل معاملات page وpageSize وsort وfilter، كما أن الإقرارات الضريبية الخاصة بدولة معين تُرجع رمز الخطأ 422 في حال كانت الشركة مسجلة خارج تلك الدولة.