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

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

المتطلبات

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

عنوان الخادم

يعمل الخادم بنقل Streamable HTTP على المسار:

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

الترقية من الإصدارات الأقدم

كانت الإصدارات الأقدم تعرض الخادم بنقل SSE على المسار /basic-services/mcp/sse. استُبدلت تلك النقطة — حدّث إعدادات العملاء الحالية إلى العنوان الجديد وغيّر نوع النقل من sse إلى http.

المصادقة

يصادق الخادم كل طلب على حدة عبر بيانات اعتماد 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 في مجلد المشروع:

json

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

Claude Desktop

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

MCP Inspector

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

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

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

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

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

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

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

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

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

المدخل	إلزامي	الوصف
`query`	لا	المصطلح المراد البحث عنه، مثل `فاتورة مبيعات` أو `sales invoice`. اتركه، أو أرسل `*`، لتصفّح القائمة كاملةً بدل البحث
`page`	لا	رقم الصفحة (يبدأ من 1) في وضع التصفّح
`pageSize`	لا	حجم الصفحة في وضع التصفّح — 50 افتراضيًا و200 كحد أقصى

تعيد الأداة حتى 25 نتيجة، كل نتيجة تحمل entityType (الاسم الداخلي مثل SalesInvoice) والاسمين العربي والإنجليزي. وفي وضع التصفّح تعيد totalEntityTypes والصفحة المطلوبة منها. وقيمة entityType التي تعيدها هي القيمة المعتمدة، تُمرَّر كما هي — وهي حساسة لحالة الأحرف — إلى كل أداة أخرى.

import_DescribeFields — الحقول التي تستطيع البحث بها

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

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

وهي ليست القائمة نفسها التي يعيدها GetImportSchema: فهي تحمل أيضًا حقول النظام مثل creationDate التي يمكن البحث بها ولا يمكن استيرادها أبدًا، وتُعلِّم الحقول المحسوبة التي قد لا يصلح البحث بها أصلًا.

import_SearchByTranslation — البحث عن كيان أو حقل أو خيار بالاسم

أوسع أدوات الاستكشاف: مصطلح واحد بالعربية أو الإنجليزية يدخل، فيخرج كل ما قد يعنيه — أنواع الكيانات، وحقول أي كيان، وثوابت القوائم، كلٌّ باسميه.

المدخل	إلزامي	الوصف
`query`	نعم	المصطلح المراد البحث عنه بالعربية أو الإنجليزية
`limit`	لا	أقصى عدد نتائج — 25 افتراضيًا و100 كحد أقصى

كل نتيجة تحمل kind: إما entity (ومعها entityType)، أو field (ومعها entityType و fieldId)، أو enum (ومعها enumType و value). استخدمها حين تعرف ما سمّاه المستخدم ولا تعرف أيًّا من الثلاثة يقصد.

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

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

المدخل	إلزامي	الوصف
`entityType`	نعم	نوع الكيان، مثل `SalesInvoice`
`criteria`	لا	فلتر معايير نصي بصيغة نما — كل شرط على هيئة `fieldId,operator,value,logic;`، مثل `code,Equal,INV-1,AND;` أو `valueDate,GreaterThanOrEqual,01-01-2024,AND;` (التواريخ بصيغة `dd-MM-yyyy`)
`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_GetEntitySchema — الجداول والأعمدة خلف الكيان

بينما تتحدث بقية الأدوات بمعرفات الحقول، تجيب هذه بلغة SQL: اسم جدول الكيان، وأعمدته بأنواعها ومع الكيان الذي يشير إليه العمود المرجعي، وأعمدة المفاتيح الأجنبية، والتفاصيل نفسها لكل جدول تفصيلي بما فيها اسم الجدول الابن والعمود الذي يربطه بالرأس.

المدخل	إلزامي	الوصف
`entityType`	نعم	نوع الكيان، مثل `SalesInvoice`

وتحتاجها حين تكتب شيئًا يستعلم من قاعدة البيانات مباشرة بدل المرور عبر بوابات الكيانات — أداة SQL للقراءة فقط، أو تقريرًا.

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

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

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

تعيد الأداة أيضًا example: سجلًا هيكليًا بقيم بديلة بالشكل الذي تتوقعه ImportRecord تمامًا. المبالغ والكميات تحتفظ بتداخلها الحقيقي ولا تُكتب بمفاتيح منقّطة — فمثلًا الجانب المدين في سند القيد يُكتب "debit": { "value": { "amount": 1500, "currency": "EGP" }, "rate": 1, "localAmount": 1500 }. وحقول التاريخ تحمل تلميح format: التاريخ يُكتب باليوم أولًا dd-MM-yyyy أو بصيغة ISO ‏yyyy-MM-dd، والتاريخ مع الوقت yyyy-MM-dd'T'HH:mm (والتاريخ وحده يُعامل على أنه منتصف الليل).

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

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

المدخل	إلزامي	الوصف
`recordsJson`	نعم	السجلات المراد استيرادها
`importMode`	نعم	`CreateOnly`: إضافة فقط — الكود الموجود مسبقًا خطأ؛ `UpdateOnly`: تعديل الموجود فقط — الكود غير المعروف خطأ؛ `CreateOrUpdate`: السماح بالاثنين. تُطابَق السجلات بالكود، لذا `CreateOnly` هو الخيار الآمن كلما كان القصد الإضافة
`saveAsDraft`	لا	`true`: حفظ كمسودة غير معتمدة — `false` (الافتراضي): حفظ واعتماد
`appendDetailLines`	لا	يؤثر فقط عند تعديل سجل موجود: `true` يُبقي بنوده الحالية ويضيف المرسلة بعدها — `false` (الافتراضي) يستبدلها، فأي بند لم يُرسل يُفقد

الأكواد. المستند الذي يرقّمه دفتره تلقائيًا (أو الملف الرئيسي الذي تُرقّمه مجموعته) لا يحتاج code: اتركه والرقم الحقيقي يُخصَّص عند الاعتماد. ويُقبل أيضًا كود مؤقت يبدأ ببادئة الدفتر وينتهي بـ @draft — مثل JE1000@draft — ويُستبدل بالطريقة نفسها. اللاحقة @draft تعني فقط أن الكود مؤقت؛ أما اعتماد السجل من عدمه فيقرره saveAsDraft وحده. وقد يعود سجل معتمد بحالة بانتظار الاعتماد حين ينطبق عليه تعريف اعتماد — وهذا من ميزة الاعتمادات لا من الاستيراد.

الشكل العام:

json

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

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

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

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

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

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

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

عنوان الخادم ​

المصادقة ​

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

Claude Code ​

Claude Desktop ​

MCP Inspector ​

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

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

import_DescribeFields — الحقول التي تستطيع البحث بها ​

import_SearchByTranslation — البحث عن كيان أو حقل أو خيار بالاسم ​

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

import_GetRecord — قراءة سجل ​

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

import_GetEntitySchema — الجداول والأعمدة خلف الكيان ​

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

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

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