الانتقال إلى المحتوى الرئيسي

​
النطاقات وأذونات الأدوار

يعمل الموصل ضمن النطاقين didit:management وdidit:verification، ويُعلَن عن نطاق ثالث هو didit:staff، لكنه لا يؤثر إلا في حسابات موظفي Didit. يُفرض الحدّان في كل استدعاء: يحمل الرمز النطاقات التي وافقتَ عليها، وضمن هذه النطاقات يحدد دورك في وحدة التحكم ما يمكنك فعله. الوصول الفعلي هو تقاطع الأمرين، لذا فإن الموافقة على didit:verification فقط تُبقي سطح الإدارة مغلقاً حتى بالنسبة إلى OWNER. يرتبط كل أداة بإذن خلفي واحد (مثل read:sessions وwrite:workflows وdelete:lists، ويعرض مرجع الأدوات الإذن الخاص بكل أداة). يتحقق الخادم مسبقاً من هذا الإذن باستخدام أذونات المؤسسة التي يعيدها استبطان الرمز، ويتحكم في ذلك المتغير MCP_PERMISSION_MODE: لا يتجاوز MCP دورك أبداً. ويعني الرد 403 على أداة واحدة أن دورك يفتقر إلى ذلك الإذن، ولا يعني أن الاتصال كله قد فشل.

​
حلّ النطاقات عبر التطبيقات والمؤسسات

تُحدَّد واجهة برمجة إدارة Didit لكل تطبيق (/organization/{org}/application/{app}/…). ويحدد MCP النطاق عنك:
  • مؤسسة واحدة وتطبيق واحد ← يُحدَّد تلقائياً، ولا تحتاج إلى تمرير أي معرّف.
  • تطبيقات متعددة ← تجمع الأدوات العابرة للتطبيقات (didit_session_search وdidit_transaction_search وdidit_case_search وdidit_vendor_user_search وdidit_vendor_business_search وdidit_workflow_search وdidit_analytics) النتائج من جميع التطبيقات في استدعاء واحد، ويُوسم كل صف بـ organization_id وapplication_id الخاصين به.
  • تمتد أدوات القائمة الخاصة بكل تطبيق (didit_session_list وdidit_transaction_list وdidit_case_list وdidit_vendor_user_list وdidit_vendor_business_list وdidit_workflow_list) تلقائياً عبر كل التطبيقات عندما لا تحدد تطبيقاً، فيعمل طلب “اعرض جلساتي” البسيط حتى مع تطبيقات كثيرة. مرّر organization_id وapplication_id لتضييق النتائج إلى تطبيق واحد.
استخدم didit_context_get لعرض كل مؤسساتك وتطبيقاتك ومعرّفاتها في استدعاء واحد. كما يعرض الأداة mode لكل تطبيق (live أو sandbox)، فلا تخمّن البيئة من اسم التطبيق أبداً. ويقبل didit_session_create القيمة sandbox_scenario على تطبيقات البيئة التجريبية لتشغيل اختبارات غير محسوبة في الفوترة.

​
ما يحتويه الكتالوج المستضاف

يمنحك الموصل المستضاف 169 أداة. ويتضمن أيضاً 17 أداة من Investigator، وهي لا تعمل إلا بعد تفعيل Investigator لمؤسستك. وهناك أداتان إضافيتان، هما didit_org_top_up (الدفع عبر Stripe) وdidit_org_reveal_application_api_key (السر الخام)، مخفيتان من tools/list لكل مستدعٍ مصادَق عليه عبر OAuth. أما أدوات إعداد الحساب الخمس (didit_account_*) فمستبعدة تماماً من الخوادم عن بُعد، وترفض التشغيل هناك، لأن الموصل عن بُعد يجب ألا يتلقى بيانات الاعتماد كمعاملات للأدوات أبداً. ويحتفظ خادم stdio المحلي بها كلها، أي 193 أداة في المجموع. يحمل كل أداة مدرجة تعليقات توضيحية من MCP (readOnlyHint وdestructiveHint وopenWorldHint وعنوان title) وoutputSchema، وتسمية _meta["anthropic/toolGroup"] التي تسمّي مجالها (الجلسات، وسير العمل والاستبيانات، والمعاملات (AML)، وغيرها). ويستخدم العملاء مثل Claude هذه التعليقات التوضيحية لتقسيم أدوات الموصل إلى مجموعات للقراءة فقط، وأخرى للكتابة، وأخرى للإجراءات المدمّرة.

​
سير العمل المتفرع

سير العمل البسيط هو قائمة مسطّحة من الميزات. أما المنطق الشرطي، مثل الرفض عند حالة معينة، أو التوجيه وفق حقل مستخرج، أو إتاحة خطوة أو حجبها بناءً على نتيجة مطابقة، أو إضافة طلب Document-AI، فيستخدم فيه MCP مخطط العقد في Didit، وهو البنية نفسها التي يستخدمها المنشئ المرئي في الكونسول. يُكتب المخطط بالشكل { start_node, nodes }، وكل عقدة إما feature أو branch أو status (طرفية) أو action أو webhook. تدعم قواعد الفروع عدة عوامل، منها fuzzy_match (للحقول النصية، مع عتبة تشابه score من 0 إلى 100) على الحقول المستخرجة مثل kyc.extra_fields.profession. وتطلب عقدة الميزة DOCUMENT_AI المستندات (مثل إثبات الأموال).

​
تعديل سير عمل موجود (موصى به)

سير العمل الحقيقي يحمل إعدادات ميزات كبيرة: فقد تبلغ قائمة السماح documents_allowed الخاصة بـ OCR 150 KB أو أكثر، إضافة إلى قوائم إثبات العنوان وقوائم الدول الخاصة بأرقام الهاتف. لذلك لا تقرأ المخطط كاملاً ثم تعيد إرساله. بدلاً من ذلك، عدّله باستخدام عمليات صغيرة:
1

تحديد الموقع وفحصه

يبحث didit_workflow_search { workflow_id } عن سير العمل في جميع تطبيقاتك. ويعيد didit_workflow_get_graph البنية مع تلخيص الإعدادات الكبيرة، فلا يتجاوز الحد أبداً (ومرّر include_config: true للحصول على القيم الخام). أما didit_workflow_get_field_definitions فيسرد الحقول القابلة للتفرع والعوامل الصالحة لها.
2

التعديل بالعمليات

يقبل didit_workflow_edit_graph عدداً قليلاً من العمليات الصغيرة، مثل set_next وset_node وset_branches وmerge_node_config. ويجلب MCP المخطط الكامل من جهة الخادم، ثم يطبّق العمليات ويتحقق منها وينشئ مسودة تلقائياً ويحفظها. تبقى قوائم السماح محفوظة بايتاً بايت، ولا تمرّ عبر الطلب أبداً. ويعيد فشل التحقق القيمة applied: false، ولا يُحفظ شيء.
3

المراجعة والنشر

تبقى المسودة قابلة للمراجعة إلى أن تنشرها بالأمر publish (من الكونسول أو عبر didit_workflow_publish). ولا تُمسّ النسخة الحية أبداً.
فمثلاً، لإدراج فرع بعد التحقق من الهوية يعود إلى خط المعالجة الحالي لديك، يكفي أن ترسل فقط: إعادة توصيل next الخاصة بعقدة OCR إلى الفرع الجديد، وإضافة الفرع، وعقدة Declined نهائية، وخطوة DOCUMENT_AI (يشير next فيها إلى الخطوة التالية الأصلية). أما العقد العشر الأخرى وقوائم السماح الخاصة بها فتبقى دون تغيير.
“بعد التحقق من الهوية، إذا رُفض فارفضه؛ وإذا كانت المهنة ≈ ‘Software Engineer’ (بنسبة ≥80%)، فاطلب إثبات الأموال؛ ثم تابع.” ← عقدة branch واحدة: kyc.status == Declined ← عقدة حالة Declined؛ وkyc.extra_fields.profession fuzzy_match “Software Engineer” بدرجة 80 ← عقدة DOCUMENT_AI لإثبات الأموال؛ ومسار وإلا يعود إلى خط المعالجة.
يجب أن يتضمن الفرع دائماً مساراً وإلا صريحاً. المسار الافتراضي (أي المسار الذي يُسلك عندما لا يتحقق أي شرط) يجب أن يكون فرعاً بقائمة rules فارغة، مثل { "id": "else", "rules": [], "goto": "<liveness>" }، وليس الـnext المجرد لعقدة الفرع. يحوّل MCP (والخادم الخلفي) الـnext الخاص بعقدة الفرع تلقائياً إلى فرع وإلا، حتى لا يظهر الفرع كحافة ملتبسة بلا مسار وإلا مرئي.
لبناء سير عمل جديد من الصفر، استخدم didit_workflow_validate_graph ثم didit_workflow_set_graph (للمخطط الكامل)، أو اترك didit_workflow_build_graph يجمع مخططاً كاملاً من مواصفة ميزات بسيطة دون حفظه. حتى didit_workflow_create البسيطة تُحفظ بوصفها مخطط العقد نفسه: إذ يجمع MCP قائمة features لديك في عقد ميزات متسلسلة تنتهي بحالة قرار تلقائي، فتعمل الميزات فعلاً. وينشر سير العمل افتراضياً، ومرّر status: "draft" لإبقائه غير منشور. انظر إنشاء سير العمل: التفرع وسير العمل القائم على العقد للاطلاع على بنية JSON الكاملة.

​
فروع أسباب تخطي NFC باستخدام MCP

بالنسبة إلى مخطط جديد، اطلب:
“أنشئ مسودة سير عمل تتضمن التحقق من الهوية يليه NFC. إذا كانت قيمة nfc.skip_reason هي DEVICE_WITHOUT_NFC أو DOCUMENT_WITHOUT_CHIP، فأرسل الجلسة إلى قيد المراجعة؛ وفي غير ذلك فوافق عليها. احتفظ بفرع وإلا صريح، وتحقق من صحة المخطط قبل الحفظ.”
ينبغي للوكيل استدعاء didit_workflow_get_field_definitions ثم didit_workflow_validate_graph ثم didit_workflow_set_graph. وبالنسبة إلى سير عمل موجود، اطلب:
“عدّل سير العمل 26d33c04…: بعد عقدة NFC الخاصة به، وجّه أي قيمة من القيم السبع المعروفة لـ nfc.skip_reason إلى قيد المراجعة، واحتفظ بمسار NFC الناجح الحالي بوصفه مسار وإلا الصريح. احفظ مسودة، ولا تنشرها.”
ينبغي للوكيل استدعاء didit_workflow_search ثم didit_workflow_get_graph ثم didit_workflow_get_field_definitions ثم didit_workflow_edit_graph. وتطبّق أداة التعديل العمليات الصغيرة من جهة الخادم، فتحافظ على العقد غير المرتبطة وعلى قوائم السماح الكبيرة. انظر إنشاء سير العمل: التفرع بحسب سبب عدم تشغيل NFC للاطلاع على القيم السبع، وقواعد equals/in، وسلوك null، ومخطط مرتب كامل.

​
إعدادات الميزات وقوائم السماح

تحدد إعدادات config الخاصة بعقدة الميزة ما تقبله. ويعيد didit_workflow_get_feature_config_schema كل مفتاح تأخذه كل ميزة، مع أنواعه وقيمه الافتراضية. وتجيب أداتا الكتالوج (didit_workflow_get_id_verification_methods_catalog وdidit_workflow_get_kyb_registry_catalog) عن الأسئلة التي يحددها الخادم وتتوقف عليها الإعدادات. وصيغة قائمة السماح القياسية لـ OCR مُصنَّفة حسب الدولة، ثم حسب المستند، ثم كائن: { "<ISO3>": { "<CODE>": { "enabled": 1 } } } (مثل { "ESP": { "P": { "enabled": 1 } } }). ويطبّع MCP الصيغ الأسهل نيابةً عنك قبل التحقق، فلست مضطراً إلى كتابة هذه البنية يدوياً: يتبع poa_languages_allowed الخاص بـ PROOF_OF_ADDRESS الفكرة نفسها: مرّر مصفوفة لغات (["es"]) أو خريطة ({ "es": 1 }). تسري هذه التسهيلات أينما قدّمت إعدادات ميزة إلى MCP: ميزات didit_workflow_create، وإعدادات config الخاصة بالعقد في set_graph وedit_graph وvalidate_graph.

​
شكل الاستجابة (عقد V3)

تُعيد كل أداة نص JSON الأصلي لنقطة نهاية REST الأساسية دون تعديل. وهناك أمران يجب معرفتهما:
  • الأدوات المتزامنة (سير العمل، والفوترة، وverify_* المستقلة، وإدارة القوائم) تُعيد نتيجتها النهائية ضمن الاستجابة مباشرة، فتتصرّف بناءً عليها في الدورة نفسها.
  • إنشاء الجلسة غير متزامن: يُعيد didit_session_create رابط url يجب على المستخدم إكمال العملية عبره، ويصل القرار عبر webhook أو عبر didit_session_get_decision.
مفاتيح القرار دائماً مصفوفات بصيغة الجمع مع node_id لكل عنصر (id_verifications[]، وliveness_checks[]، وface_matches[]، وaml_screenings[]، وpoa_verifications[]، وphone_verifications[]، وemail_verifications[]، وdatabase_validations[]، وreviews[]، إضافةً إلى registry_checks[] وdocument_verifications[] وkey_people_checks[] الخاصة بـ KYB). راجع نماذج البيانات وحالات التحقق.

​
التعامل مع webhooks

اجعل webhook يُسلّم القرار النهائي إلى الخادم الخلفي الخاص بك، بدلاً من أن يستعلم عنه الوكيل باستمرار:
  1. يستدعي الوكيل didit_webhook_create مرةً واحدة مع label وعنوان url العام عبر HTTPS الخاص بك وwebhook_version: "v3" وsubscribed_events (عادةً ["status.updated", "data.updated"]). تُخفي الاستجابة المفتاح السري للتوقيع، وكذلك تفعل didit_webhook_get وdidit_webhook_list. انسخه من Webhooks في وحدة التحكم واحفظه باسم DIDIT_WEBHOOK_SECRET.
  2. يتحقق الخادم الخلفي من الترويسة X-Signature-V2 المعيارية في كل عملية تسليم: shortenFloats → sortKeys → JSON.stringify (مع unicode غير مُهرَّب) → HMAC-SHA256 → timingSafeEqual. ارفض الطلب إذا تجاوز الفرق abs(now − X-Timestamp) > 300 ثانية.
  3. أزِل التكرار باستخدام event_id. أعد 2xx خلال 5 ثوانٍ، وانقل المهام الثقيلة إلى قائمة الانتظار.
  4. تعيد Didit المحاولة عند 5xx / 404 حتى مرتين (بعد نحو دقيقة، ثم نحو أربع دقائق)، ثم تُسقط التسليم. أعد إرسال التسليمات الفاشلة من تبويب التسليمات في وحدة التحكم.
يحتاج الوكيل فقط إلى ربط جهة الاستقبال، ولا يستمع بنفسه. العقد الكامل: webhooks.

​
النقل و endpoints

endpoint تدعم جيلين. فالعملاء الذين يثبّتون إصدار بروتوكول 2026-07-28 أو أحدث في كل رسالة يتخطّون مرحلة initialize ويمكنهم استدعاء server/discover. أما كل العملاء الأقدم (Claude Code وCursor والعملاء المبنيون على SDK) فيستخدمون مصافحة Streamable HTTP القياسية دون تغيير. وCORS مفتوح، لذلك يستطيع العملاء المعتمدون على المتصفح (موصّل Claude على الويب وMCP Inspector) الوصول إلى /mcp ووثائق الاكتشاف عبر النطاقات. حد جسم JSON هو 25 ميغابايت، وهو يكفي لملف إدخال بصيغة base64 حجمه 15 ميغابايت.

​
استكشاف الأخطاء وإصلاحها

دورك في تلك المؤسسة يفتقر إلى الإذن الذي تحتاجه الأداة (مثلاً READER يحاول تنفيذ عملية كتابة)، وخطأ missing_scope يسمّيه. إذا فشلت كل الأدوات، فأعد الاتصال أو أعد تشغيل تسجيل الدخول باستخدام Didit. (MCP يعتمد على Bearer/OAuth فقط: مفتاح x-api-key يُرفض من كل الأدوات، لذلك لن يحل مفتاح API مشكلة 403.)
الأدوات المدمِّرة تتطلب تأكيداً في العميل الذي تستخدمه. وافق على الاستدعاء، أو تحقّق من أن طلب تأكيد الأداة لا يُرفض تلقائياً. وتحتاج didit_session_delete وdidit_session_batch_delete وdidit_org_reveal_application_api_key إضافةً إلى ذلك إلى confirm: true في معاملات الأداة. وبدونه يُرفض الاستدعاء قبل أي تنفيذ.
ربما لديك عدة تطبيقات. استخدم أداة *_search (التي تشمل كل شيء) أو شغّل didit_context_get ومرّر organization_id / application_id الذي تريده.
بعض العملاء (Windsurf وZed) يتصلون عبر جسر mcp-remote. تأكد من وجود npx -y mcp-remote@latest https://mcp.didit.me/mcp في الإعداد. أعد فتح العميل لإعادة تشغيل مصافحة OAuth.
تأكد من أن الخادم متصل (معظم العملاء يعرضون نقطة حالة) وأنك أكملت تسجيل الدخول باستخدام Didit. أعد تشغيل مضيف MCP بعد تعديل إعداده. والأداتان didit_org_top_up وdidit_org_reveal_application_api_key لا تظهران أبداً في الموصل المستضاف.
تأكد من أنك تشير إلى https://mcp.didit.me/mcp وليس إلى النطاق الجذري https://mcp.didit.me فقط. بيانات المورد تُقدَّم عند /.well-known/oauth-protected-resource/mcp ومحصورة بهذا المسار، مع نسخة في جذر النطاق للعملاء الذين يبحثون هناك. إذا كنت تستضيف بنفسك، فغالباً يعني هذا أن MCP_RESOURCE_URI مضبوط على الأصل بدلاً من عنوان النقل الكامل. راجع الاستضافة الذاتية.
مع endpoint المستضاف، أرسل الملف كـ *_base64 (base64 خام أو رابط data:). أما *_path فيعمل فقط على خادم stdio محلي. والملفات محدودة بـ 15 ميغابايت، ويجب أن تكون PNG أو JPG أو WebP أو GIF أو BMP أو ICO أو PDF بحسب محتواها الفعلي، لا بامتدادها فقط.

​
الأمان

يعمل MCP بصلاحياتك الفعلية، ويمكنه تعديل الموارد الحية. أبقِ خيار “review tool calls before running” مفعّلاً في عميلك، خاصة لأدوات Write وDestructive. لا يخزّن خادم MCP نفسه أي سر في إعداداتك (فهو يستخدم تسجيل الدخول باستخدام Didit)، ويحجب مفاتيح API وأسرار توقيع webhook في مخرجات الأدوات، ويُخفي أدوات شحن الرصيد والمفتاح الخام من الكتالوج المستضاف، ولا يقبل أبداً بيانات اعتماد الحساب كمعاملات للأدوات على الخادم البعيد. يُسجَّل كل استدعاء للأداة في سجل التدقيق الخاص بالخادم، مع المستدعي والأداة ونتيجة فحص الإذن.

​
حقن الأوامر

ترجع أدوات Didit ما كتبه مستخدموك أو رفعوه، مثل الأسماء ونص المستندات وإجابات الاستبيانات. الشخص الذي يجري التحقق منه يتحكم في هذا النص، فقد يكتب تعليمات موجّهة إلى وكيلك داخل اسم أو مستند، ويُرجع الخادم هذه الحقول كما التُقطت. لا يستطيع الوكيل أن يميّز هذا النص بموثوقية عن تعليماتك، لذا عامل كل نتيجة أداة على أنها بيانات:
  • أبقِ موافقة الأدوات مفعّلة لأدوات Write وDestructive، واقرأ ما يوشك الوكيل على فعله قبل أن توافق عليه.
  • سجّل الدخول بعضو يتناسب دوره مع المهمة. الوكيل الذي يقرأ الجلسات فقط يمكنه استخدام عضو بدور READER، ويرفض الخادم الخلفي كتاباته مهما حاول الوكيل.
  • جرّب وكيلاً جديداً أو تعليمة جديدة على تطبيق في البيئة التجريبية أولاً.
  • لا توافق على عملية تحقق أو ترفضها لأن نصاً داخلها يطلب ذلك. اعتمد على القرار وتحذيراته ومراجعتك الخاصة.

​
البيانات الشخصية

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

​
الاستضافة الذاتية

يُبنى الخادم المستضاف من github.com/didit-protocol/mcp (ترخيص MIT). انسخه وشغّله باستخدام Docker أو Node؛ فهو يصادق دائماً بوصفه مستخدم Didit (لا يوجد وضع مفتاح API)، في كلتا وسيلتي النقل. تجد خطوات الإعداد في التثبيت ← الاستضافة الذاتية.

​
متغيرات البيئة

يوجد الملف .env.example في المستودع نموذجاً قابلاً للنسخ، ويشرح ARCHITECTURE.md الفصل بين خادم الموارد وخادم التفويض. عند الإقلاع، يجلب خادم HTTP وثيقة الاكتشاف الخاصة بخادم التفويض، ويعود إلى الروابط المُعدّة إذا تعذّر الوصول إليه.

مرجع الأدوات

كل أداة، مجمّعة حسب المجال.

الأمثلة

موجّهات ومحادثات كاملة من البداية إلى النهاية.
آخر تعديل في ٧ نوفمبر ٢٠٢٦