خادم MCP لنظام نما ERP

بروتوكول MCP (Model Context Protocol) هو المعيار المفتوح الذي تتصل به مساعدات الذكاء الاصطناعي — مثل Claude Desktop و Claude Code وغيرهما — بالأنظمة الخارجية لتقرأ بياناتها وتنفذ أوامر فيها. يحتوي نظام نما ERP على خادم MCP مدمج: بمجرد تركيب وحدة الذكاء الاصطناعي، يستطيع أي عميل MCP الاتصال بالنظام مباشرة واستخدام الأدوات المعرفة في شاشة AI Tool Definition — يبحث في السجلات، يقرأ المستندات، يشغّل التقارير، بل ويستورد سجلات جديدة — وكل ذلك بحساب مستخدم حقيقي تسري عليه كل صلاحيات النظام.

المتطلبات

• وحدة الذكاء الاصطناعي (AI Module) مركبة ومرخصة — بدونها لا يعمل الخادم أصلًا.
• سجل API Credentials معتمد (نفس بيانات الاعتماد المستخدمة مع الواجهة البرمجية REST).
• أداة واحدة على الأقل معرفة ومعتمدة في شاشة AI Tool Definition.

عنوان الخادم

يعمل الخادم بنقل SSE (Server-Sent Events) على المسار:

http[s]://<server-ip-or-domain>/basic-services/mcp/sse

(يتكفل الخادم تلقائيًا بالإعلان عن نقطة استقبال الرسائل /basic-services/mcp/message الصحيحة.)

المصادقة

يصادق الخادم كل طلب على حدة عبر بيانات اعتماد API:

الترويسة (Header)	القيمة	إلزامية
X-API-Key	حقل Client Secret من سجل API Credentials	نعم
X-API-Secret	حقل API Secret — يُرسل فقط إذا كان الاعتماد يتطلب سرًّا إضافيًا	لا

(تُقبل القيم أيضًا بأسماء بديلة: apiKey/clientId لمفتاح الوصول و apiSecret/clientSecret للسر — ترويسةً أو ضمن معاملات الرابط.)

سجل API Credentials يربط بيانات الاعتماد بمستخدم محدد عبر حقل Login As User، ويدعم تقييد فترة الصلاحية (Valid From / Valid To) وإيقاف الاعتماد (Prevent Login). كل أداة يستدعيها العميل تُنفَّذ بهوية ذلك المستخدم: صلاحيات السجلات، والمحددات (الشركة والفرع وغيرها)، وقواعد التحقق — كلها تسري كأن المستخدم يعمل من شاشات النظام.

احمِ بيانات الاعتماد

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

إعداد العملاء

Claude Code

أضف الخادم إلى ملف .mcp.json في مجلد المشروع:

{
  "mcpServers": {
    "nama-erp": {
      "type": "sse",
      "url": "https://my-server.example.com/basic-services/mcp/sse",
      "headers": {
        "X-API-Key": "<client-secret>"
      }
    }
  }
}

Claude Desktop

في ملف الإعدادات claude_desktop_config.json أضف نفس التعريف ضمن mcpServers.

MCP Inspector

أداة الفحص الرسمية للبروتوكول تعمل من المتصفح مباشرة (الخادم يسمح بطلبات CORS): اختر النقل SSE، وأدخل العنوان، وأضف ترويسة المصادقة.

بعد الاتصال، استعرض قائمة الأدوات من العميل — ستجد كل الأدوات المعتمدة وغير المعطلة من شاشة AI Tool Definition، وأي تعديل على التعريفات ينعكس تلقائيًا في الاتصال التالي.

ليست أدوات التصدير وحدها

الخادم يعرض كل أداة معتمدة ومسموح بها للمستخدم المربوط بالاعتماد — أدوات استعلام وتقارير ومسارات كيان وأدوات نظام — لا أدوات التصدير الست فقط. هذه الصفحة تفصّل أدوات التصدير لأهميتها مع العملاء الخارجيين، وبقية الأنواع موثقة في تعريفات أدوات الذكاء الاصطناعي.

أدوات تصدير واستيراد السجلات

المجموعة الأهم للاستخدام مع عملاء MCP الخارجيين هي أدوات النظام الست للتصدير والاستيراد، وتُضاف دفعة واحدة بزر إضافة أدوات التصدير (Add Export Tools) في صفحة System Tool من شاشة تعريف الأداة (انظر تعريفات أدوات الذكاء الاصطناعي).

تُسمّى الأدوات ببادئة من تعريف الأداة (حقل Tool Name أو Alt Code أو الكود). في الأمثلة التالية نفترض أن البادئة import.

import_ResolveEntityType — تحويل مصطلح إلى نوع كيان

نقطة البداية لأي عميل لا يعرف أسماء الكيانات الداخلية. أرسل مصطلحًا بالعربية أو الإنجليزية، واستلم أنواع الكيانات المطابقة بأسمائها المترجمة.

المدخل	إلزامي	الوصف
query	نعم	المصطلح المراد البحث عنه، مثل فاتورة مبيعات أو sales invoice

تعيد الأداة حتى 25 نتيجة، كل نتيجة تحمل entityType (الاسم الداخلي مثل SalesInvoice) والاسمين العربي والإنجليزي.

import_FindRecords — البحث عن سجلات

بحث مرقّم الصفحات عن سجلات نوع كيان، يمر عبر بوابة العرض القياسية فتسري عليه صلاحيات القوائم والمحددات.

المدخل	إلزامي	الوصف
entityType	نعم	نوع الكيان، مثل SalesInvoice
criteria	لا	تعبير معايير بصيغة نما، مثل code = 'INV-1' أو the60 >= '2024-01-01'
fields	لا	معرفات حقول إضافية تُعاد في كل صف (مفصولة بفواصل) — يُعاد دائمًا id و code
orderBy	لا	معرف حقل للترتيب
page	لا	رقم الصفحة (يبدأ من 1)
pageSize	لا	حجم الصفحة — الافتراضي 25 والحد الأقصى 200

تعيد الأداة totalRecordsCount ورقم الصفحة وحجمها ومصفوفة records.

import_GetRecord — قراءة سجل

يقرأ سجلًا واحدًا بصيغة JSON عبر بوابة القراءة القياسية. الناتج بنفس صيغة الاستيراد، فيمكن قراءة سجل وتعديله وإعادة استيراده.

المدخل	إلزامي	الوصف
entityType	نعم	نوع الكيان
idOrCode	نعم	كود السجل أو معرفه
mode	لا	visible (الافتراضي): الحقول الظاهرة على الشاشة فقط — أو all: كل الحقول
fields	لا	معرفات حقول محددة تُعاد وحدها (تتجاوز mode)

import_GetEnumValues — القيم المسموحة لحقل قائمة

المدخل	إلزامي	الوصف
entityType	نعم	نوع الكيان صاحب الحقل
fieldId	نعم	معرف الحقل، مثل invoiceLines.discountType

تعيد قائمة القيم مع عنوان كل قيمة بالعربية والإنجليزية — مفيدة قبل الاستيراد لضمان إرسال الثوابت الصحيحة.

import_GetImportSchema — مخطط الاستيراد

يصف كيفية بناء سجل لنوع كيان: كل حقل ونوعه وهل هو إلزامي، والقيم المسموحة لحقول القوائم، ونوع الكيان المستهدف للحقول المرجعية (المراجع تُكتب بالكود)، وبنية الجداول التفصيلية (مثل بنود الفاتورة).

المدخل	إلزامي	الوصف
entityType	نعم	نوع الكيان
mode	لا	visible (الافتراضي): الحقول الظاهرة على الشاشة — وهي ما يملؤه المستخدم عادة — أو all: كل الحقول القابلة للاستيراد
collections	لا	حصر الجداول التفصيلية المعادة (أسماء مفصولة بفواصل، مثل invoiceLines) — حقول الرأس تُعاد دائمًا

import_ImportRecord — استيراد سجلات

يستورد سجلًا أو أكثر بصيغة JSON الخاصة بنما: كائن مفاتيحه أنواع الكيانات وقيمه مصفوفات سجلات.

المدخل	إلزامي	الوصف
recordsJson	نعم	السجلات المراد استيرادها
saveAsDraft	لا	true: حفظ كمسودة غير معتمدة — false (الافتراضي): حفظ واعتماد

الشكل العام:

{
  "SalesInvoice": [
    {
      "code": "INV-1001",
      "customer": "C-0005",
      "invoiceLines": [ { "...": "حقول البند كما يصفها مخطط الاستيراد" } ]
    }
  ]
}

(المراجع — كالعميل والصنف — تُكتب بالكود مباشرة، والبنية الدقيقة لكل كيان هي ما تعيده أداة GetImportSchema؛ والأسلوب الأضمن أن يقرأ العميل سجلًا موجودًا بأداة GetRecord ويحاكي شكله.)

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

سيناريو عمل متكامل

النمط المعتاد الذي يتبعه عميل MCP لاستيراد بيانات:

1. import_ResolveEntityType: «فاتورة مبيعات» ← SalesInvoice.
2. import_GetImportSchema: معرفة الحقول الإلزامية وبنية بنود الفاتورة.
3. import_GetEnumValues: القيم الصحيحة لحقول القوائم (نوع الخصم مثلًا).
4. import_FindRecords: إيجاد أكواد المراجع (العميل، الصنف) قبل استخدامها.
5. import_ImportRecord: الاستيراد كمسودة أولًا للمراجعة، أو حفظ واعتماد مباشرة.
6. import_GetRecord: قراءة السجل المستورد للتحقق من النتيجة.