تكامل MCP (وصول أدوات الذكاء الاصطناعي)

يتضمّن Canopy خادم MCP مدمجًا (Model Context Protocol) يتيح لأدوات الذكاء الاصطناعي — مثل Claude Desktop وGitHub Copilot وCursor وVS Code — الاستعلام عن بيانات هندسة المؤسسة لديك وتحديثها مباشرةً. ويمكن لأدوات الذكاء الاصطناعي أيضًا رفع المُخرجات (جداول البيانات، ومخططات BPMN، ومخططات DrawIO، والمستندات الحرّة) وتحويلها إلى بطاقات وعلاقات ومخططات تتلاءم مع النموذج الفوقي القائم. يصادق المستخدمون عبر مزوّد SSO الحالي لديك، وتحترم كل عملية أذوناتهم الفردية.

هذه الميزة اختيارية ولا تبدأ تلقائيًا. فهي تتطلب إعداد SSO، وقيام أحد المسؤولين بتشغيلها من واجهة الإعدادات.

---

كيف يعمل

AI Tool (Claude, Copilot, etc.)
    │
    │  MCP protocol (HTTP + SSE)
    ▼
Canopy MCP Server (:8001, internal)
    │
    │  OAuth 2.1 with PKCE
    │  delegates to your SSO provider
    ▼
Canopy Backend (:8000)
    │
    │  Per-user RBAC
    ▼
PostgreSQL

1. يضيف المستخدم عنوان URL لخادم MCP إلى أداة الذكاء الاصطناعي لديه.
2. عند أول اتصال، تفتح أداة الذكاء الاصطناعي نافذة متصفح للمصادقة عبر SSO.
3. بعد تسجيل الدخول، يُصدر خادم MCP رمز وصول خاصًا به (مدعومًا بـ JWT الخاص بالمستخدم في Canopy). ويُجدَّد الرمز استباقيًا قبل نحو ساعة من انتهاء صلاحيته.
4. تستخدم أداة الذكاء الاصطناعي هذا الرمز لجميع الطلبات اللاحقة.
5. يمرّ كل استعلام عبر نظام أذونات Canopy المعتاد — فلا يرى المستخدمون سوى البيانات التي يملكون صلاحية الوصول إليها.

---

المتطلبات المسبقة

قبل تفعيل MCP، يجب أن يتوفّر لديك:

• SSO مُعَدّ ويعمل — يفوّض MCP المصادقة إلى مزوّد SSO لديك (Microsoft Entra ID أو Google Workspace أو Okta أو OIDC عام). راجع دليل المصادقة والدخول الموحّد.
• HTTPS مع نطاق عام — يتطلب تدفّق OAuth عنوان URI ثابتًا لإعادة التوجيه. انشر النظام خلف وكيل عكسي يُنهي اتصال TLS (Caddy أو Traefik أو Cloudflare Tunnel، وما إلى ذلك).

---

الإعداد

الخطوة 1: إضافة عنوان URI لإعادة توجيه OAuth إلى تطبيق SSO لديك

في تسجيل التطبيق لدى مزوّد SSO الخاص بك (نفس التطبيق الذي أعددته لتسجيل الدخول إلى Canopy)، أضف عنوان URI التالي لإعادة التوجيه:

https://your-domain.example.com/mcp/oauth/callback

هذا ضروري لتدفّق OAuth الذي يصادق المستخدمين عند اتصالهم من أداة الذكاء الاصطناعي لديهم.

الخطوة 2: تفعيل MCP في إعدادات المسؤول

1. انتقل إلى الإعدادات في منطقة الإدارة وحدّد علامة التبويب AI.
2. مرّر إلى قسم MCP Integration (AI Tool Access).
3. حرّك المفتاح إلى وضع التفعيل لـ MCP.
4. ستعرض الواجهة عنوان URL لخادم MCP وتعليمات الإعداد لمشاركتها مع فريقك.

warning

يكون المفتاح معطّلًا إذا لم يكن SSO مُعَدًّا. أعدّ SSO أولًا.

---

ربط أدوات الذكاء الاصطناعي

بمجرد تفعيل MCP، شارك عنوان URL لخادم MCP مع فريقك. ويضيفه كل مستخدم إلى أداة الذكاء الاصطناعي لديه:

Claude Desktop

1. افتح Settings > Connectors > Add custom connector.
2. أدخل عنوان URL لخادم MCP: https://your-domain.example.com/mcp
3. انقر Connect — تُفتح نافذة متصفح لتسجيل الدخول عبر SSO.
4. بعد المصادقة، يمكن لـ Claude الاستعلام عن بيانات هندسة المؤسسة لديك وتحديثها.

VS Code (GitHub Copilot / Cursor)

أضف ما يلي إلى ملف .vscode/mcp.json في مساحة العمل لديك:

{
  "servers": {
    "canopy": {
      "type": "http",
      "url": "https://your-domain.example.com/mcp/mcp"
    }
  }
}

التكرار المزدوج لـ /mcp/mcp مقصود — فالأول /mcp/ هو مسار وكيل Nginx، والثاني هو نقطة نهاية بروتوكول MCP.

---

القدرات المتاحة

يعرض خادم MCP 47 أداة: 30 أداة قراءة موزّعة على تسع مجموعات، و17 أداة كتابة (13 إضافية، و4 تدميرية). وتحمل كل أداة سمة ToolAnnotations (readOnlyHint / destructiveHint / idempotentHint) بحيث يمكن للموصلات مثل Claude Desktop إظهار درجة الخطورة في واجهتها قبل أن يوافق المستخدم على الاستدعاء.

أمان التشغيل التجريبي على عمليات الكتابة

تتخذ كل أداة كتابة القيمة الافتراضية dry_run=true. في هذا الوضع تُشغّل الواجهة الخلفية كل أداة تحقق ومُحلِّل مراجع، وتبني الخطة الكاملة، ثم تتراجع عن المعاملة فلا يُحفظ أي شيء. تُعيد أداة الذكاء الاصطناعي المعاينة إلى المستخدم؛ ولا ينبغي لها استدعاء الأداة مرة أخرى بـ dry_run=false للتنفيذ إلا بعد تأكيد صريح. يمنع هذا أي وكيل متحمّس من بثّ مئات البطاقات بهدوء استنادًا إلى جدول بيانات أُسيء تفسيره.

بالنسبة إلى عمليات التنفيذ الأكبر، ثمة بوابة ثانية: يجب أن يُعيد أي تنفيذ يتجاوز MCP_BATCH_CONFIRMATION_THRESHOLD (القيمة الافتراضية 20 صفًا) رمز confirm_token أحادي الاستخدام صدر عن التشغيل التجريبي السابق. ومدة صلاحية الرمز 15 دقيقة. ويُفرض هذا التحقق مرتين — مرة بواسطة غلاف MCP قبل استدعاء الواجهة الخلفية أصلًا، ومرة أخرى بواسطة الواجهة الخلفية نفسها عند نقطة نهاية التنفيذ — بحيث لا يستطيع عميل يتجاوز خطوة التشغيل التجريبي تمرير دفعة كبيرة غير مُراجَعة.

دفعات التعديل (مسار التدقيق)

يفتح كل استدعاء كتابة — سواء أكان تشغيلًا تجريبيًا أم لا — صفًا في mutation_batches قبل لمس أي بيانات، ويُوسَم كل حدث يصدر عنه (إنشاء بطاقة، تحديث علاقة، نشر تعليق، …) بمعرّف تلك الدفعة إضافةً إلى اسم الأداة المستدعية والمستخدم المصادَق عليه. تعيد أداة get_change_history بناء الفرق الكامل لكل حدث في دفعة ما انطلاقًا من معرّفها، وتستطيع rollback_batch عكس عمليات الكتابة الخاصة بدفعة ما (انظر أدناه). ويعني هذا أن أي تغيير ناتج عن MCP يمكن تتبعه بدقة لمعرفة من نفّذ أي أداة ومتى — تمييزًا له عن الإجراء نفسه المنفَّذ عبر الواجهة الإلكترونية.

أدوات القراءة

يعرض الخادم 30 أداة قراءة موزّعة على تسع مجموعات.

البطاقات والنموذج الفوقي

الأداة	الوصف
search_cards	البحث في البطاقات وتصفيتها حسب النوع أو الحالة أو النص الحرّ
get_card	الحصول على التفاصيل الكاملة لبطاقة حسب UUID
get_card_relations	الحصول على جميع العلاقات المرتبطة ببطاقة
get_card_hierarchy	الحصول على أسلاف البطاقة وأبنائها
list_card_types	سرد جميع أنواع البطاقات في النموذج الفوقي، مع الحقول والإعدادات
get_relation_types	سرد أنواع العلاقات، مع إمكانية التصفية حسب نوع البطاقة
resolve_card_refs	التحقق المسبق من صحة المراجع المستندة إلى الاسم للبطاقات (مثل "Sales / Customer Mgmt / CRM") قبل عملية استيراد مجمّعة — يُظهر التطابقات المحلولة والملتبسة والمفقودة
analyze_impact	تحليل الأثر متعدد القفزات — يجتاز رسم العلاقات البياني خارجًا من بطاقة حتى 3 قفزات، مجمّعًا حسب العمق، مع إمكانية التصفية حسب نوع العلاقة ونوع البطاقة

لوحات المعلومات

الأداة	الوصف
get_dashboard	لوحة معلومات مؤشرات الأداء KPI (الأعداد، وجودة البيانات، والموافقات، والنشاط)
get_landscape	بطاقات من نوع واحد مجمّعة حسب نوع مرتبط

GRC — سجل المخاطر

الأداة	الوصف
list_risks	قائمة مخاطر هندسة المؤسسة مقسّمة إلى صفحات وقابلة للتصفية (TOGAF المرحلة G)
get_risk	تفاصيل مخاطرة واحدة مع البطاقات المرتبطة + مسار التدقيق
get_risk_metrics	مؤشرات الأداء KPI + مصفوفات الاحتمال × الأثر 4×4 الأولية/المتبقية
get_card_risks	جميع المخاطر المرتبطة حاليًا ببطاقة محددة

GRC — الامتثال

الأداة	الوصف
list_compliance_findings	نتائج الامتثال مجمّعة حسب اللائحة التنظيمية (EU AI Act وGDPR وNIS2 وDORA وSOC 2 وISO 27001)
get_compliance_overview	درجات الامتثال + مصفوفة الحالة لكل لائحة + بيانات وصفية لآخر فحص

الحوكمة والتسليم

الأداة	الوصف
list_principles	مبادئ هندسة المؤسسة المنشورة (البيان، والمبرّر، والتبعات)
list_adrs	سجلات قرارات البنية (ADR)، قابلة للتصفية حسب المبادرة / البطاقة / الحالة / البحث
get_adr	سجل ADR واحد مع الأقسام والبطاقات المرتبطة وسجلات ADR ذات الصلة ومسار التوقيع
list_soaws	بيانات عمل البنية (SoAW) لمبادرة ما

التقارير

الأداة	الوصف
get_portfolio_report	بيانات مخطط الفقاعات لنوع بطاقة (الملاءمة الوظيفية × التقنية افتراضيًا)
get_cost_treemap	مخطط شجري لتكلفة البطاقات، مع إمكانية التجميع حسب نوع مرتبط
get_capability_heatmap	خريطة حرارية هرمية لقدرات الأعمال
get_data_quality_report	تفصيل اكتمال البيانات لكل نوع بطاقة

سياق البطاقة

الأداة	الوصف
get_card_stakeholders	المستخدمون والأدوار المُسندة إلى بطاقة
get_card_comments	التعليقات المتسلسلة على بطاقة
get_card_documents	روابط المستندات المرفقة ببطاقة

المخططات

الأداة	الوصف
list_diagrams	سرد المخططات الحرة، مع إمكانية تصفيتها حسب بطاقة واحدة
get_diagram	جلب مخطط واحد حسب المعرّف، متضمنًا XML الخاص به في DrawIO

التدقيق وسجل التغييرات

الأداة	الوصف
get_change_history	البحث عن دفعة تعديل حسب المعرّف (تُعيد الدفعة + كل حدث صدر ضمنها، بالترتيب)، أو تصفح الدفعات الأخيرة حسب الفاعل أو اسم الأداة أو المصدر (mcp / web / api)

تخضع جميع أدوات القراءة لنظام RBAC الخاص بالمستخدم المصادَق عليه — فيحصل المستخدم ذو صلاحية العرض فقط على قائمة فارغة (أو خطأ 403) للمناطق التي لا يمكنه رؤيتها؛ ولا يحتاج أي شيء على طبقة MCP إلى ضبط لكل أداة.

أدوات الكتابة

يعرض الخادم 17 أداة كتابة: 13 أداة إضافية (إجراءات إنشاء/تحديث لا تُتلف بيانات) و4 أدوات تدميرية (يمكنها الكتابة فوق بيانات أو إزالتها، مع أن عدة منها قابلة للاسترجاع بذاتها — انظر الملاحظات أدناه).

البطاقات ودورة الحياة

الأداة	التصنيف	الوصف
create_cards_bulk	إضافية	إنشاء بطاقات عديدة في استدعاء واحد انطلاقًا من صفوف مستخرجة من مُخرج (مثل صفوف جدول بيانات). يدعم مراجع الأب بالاسم ضمن الدفعة نفسها مع ترتيب طوبولوجي يُجرى على جانب الخادم.
update_cards_bulk	إضافية	تحديث بطاقات عديدة في استدعاء واحد — تصحيحات على مستوى الحقل مع فرق "قبل/بعد" لكل صف أثناء التشغيل التجريبي. الحقل attributes استبدال كامل لكل صف؛ ويرفض strict_attributes=true مفاتيح الحقول غير المعروفة مع تلميح للتصحيح.
transition_card_lifecycle	إضافية	نقل بطاقة عبر إجراءات الموافقة (approve / reject / reset)، أو مراحل دورة الحياة (phaseIn / active / phaseOut / endOfLife)، أو قيم الحالة (ACTIVE / PHASING_IN / PHASING_OUT / END_OF_LIFE / ARCHIVED). تُعيد استجابة pending مع رابط مباشر إلى الواجهة إذا كان المستدعي يفتقر إلى الإذن اللازم، بدلًا من الفشل التام.
archive_cards	تدميرية	حذف ناعم (أرشفة) لبطاقة واحدة أو أكثر، مع معاينة أثر متسلسل أثناء التشغيل التجريبي (الأبناء، والعلاقات اليتيمة). يمكن استرجاع البطاقات المؤرشفة خلال 30 يومًا قبل الحذف التلقائي النهائي. الحذف الدائم غير متاح عمدًا عبر MCP.

العلاقات والمخططات

الأداة	التصنيف	الوصف
upsert_relations_bulk	تدميرية	إنشاء أو حذف علاقات بين البطاقات. تُرفض عمليات action: "delete" افتراضيًا (انظر الضوابط أدناه) — وهذا ما يجعل هذه الأداة مصنّفة كتدميرية رغم أن الإنشاء هو الحالة الشائعة.
create_diagram	إضافية	إنشاء مخطط DrawIO حرّ الشكل، مع إمكانية ربطه ببطاقات قائمة عبر UUID.
update_diagram	تدميرية	تحديث XML أو اسم أو وصف أو البطاقات المرتبطة بمخطط قائم — يستبدل drawio_xml لوحة الرسم حرفيًا.
import_bpmn	إضافية	حفظ مخطط BPMN 2.0 مقابل بطاقة قائمة من نوع BusinessProcess، مع اجتياز سير عمل المسودة ← التقديم ← الموافقة. إذا لم توجد بطاقة مطابقة، تُعيد الأداة خطأ card_not_found يُشير إلى create_cards_bulk بدلًا من إنشاء بطاقة هزيلة بصمت.

GRC — سجل المخاطر

الأداة	التصنيف	الوصف
create_risks	إضافية	إنشاء مخاطرة واحدة أو أكثر، مع إمكانية ربط البطاقات المتأثرة في الاستدعاء نفسه.
update_risks	إضافية	تصحيح مخاطر قائمة حسب المعرّف؛ يستبدل linked_card_ids مجموعة روابط البطاقات المتأثرة عند تمريره.

الحوكمة والتسليم

الأداة	التصنيف	الوصف
create_soaw	إضافية	إنشاء بيان عمل بنية (SoAW) لمبادرة ما.
create_adr	إضافية	إنشاء سجل قرار بنية (ADR) (يبدأ في حالة draft افتراضيًا).
update_adr	إضافية	تحديث عنوان أو أقسام أو حالة أو البطاقات المرتبطة بسجل ADR قائم.
sign_adr	إضافية	توقيع سجل ADR. تُعيد استجابة pending مع رابط مباشر إذا كان المستدعي يفتقر إلى إذن adr.sign.

التعاون

الأداة	التصنيف	الوصف
add_card_comment	إضافية	نشر تعليق (متسلسل اختياريًا) على بطاقة.
assign_stakeholders	إضافية	إسناد أدوار أصحاب المصلحة على البطاقات أو إزالتها. لا تملك الواجهة الخلفية نقطة نهاية مجمّعة لذلك، فتوزّع الأداة كل عملية على حدة ضمن دفعة تعديل واحدة.

التدقيق

الأداة	التصنيف	الوصف
rollback_batch	تدميرية	التراجع عن عمليات الكتابة المنفَّذة ضمن دفعة تعديل، عبر اجتياز أحداثها بترتيب معكوس وتطبيق نقيض كل حدث. يشمل ذلك card.created / card.updated / card.archived / card.restored / relation.created / relation.upserted؛ وتظهر أنواع الأحداث الأخرى كـ unsupported_events في خطة التشغيل التجريبي. تُسجَّل عملية التراجع نفسها كدفعة جديدة، فلا يُمحى السجل التاريخي أبدًا. تُرفض العملية إذا لامست دفعة لاحقة الكيانات نفسها ما لم يُستخدم force=true، الذي يتطلب إذن admin.events.

يُعامَل المحتوى الذي تخزّنه هذه الأدوات (نصوص التعليقات، نصوص أقسام ADR/SoAW) بوصفه بيانات غير موثوقة عند قراءته لاحقًا — فلا يفسّره الخادم قط بوصفه تعليمات، بل يعرضه فقط.

سير العمل النموذجي لاستيراد المُخرجات

عندما يشارك مستخدم جدول بيانات مع وكيل الذكاء الاصطناعي:

1. يستدعي الوكيل list_card_types وget_relation_types لفهم النموذج الفوقي.
2. يحلّل الوكيل جدول البيانات (في سياقه الخاص، لا في MCP) ويبني قواميس صفوف.
3. اختياريًا، يستدعي الوكيل resolve_card_refs للتحقق من أن أي مراجع أب/علاقة مستندة إلى الاسم تُحلّ دون التباس.
4. يستدعي الوكيل create_cards_bulk(cards=…, dry_run=True) ويعرض المعاينة على المستخدم.
5. يؤكّد المستخدم؛ فيستدعي الوكيل الأداة مرة أخرى بـ dry_run=False (مع إعادة إرسال confirm_token إذا تجاوزت الدفعة عتبة التأكيد) لتنفيذ العملية.
6. إذا كانت أعمدة العلاقات موجودة، يستدعي الوكيل عندئذٍ upsert_relations_bulk بدورة التشغيل التجريبي/التأكيد نفسها.

لا يُحلّل خادم MCP نفسه الملفات المرفوعة مطلقًا — بل تقرأ أداة الذكاء الاصطناعي المُستدعِية المُخرج المصدر (جدول بيانات، أو XML لِـ BPMN، أو XML لِـ DrawIO، أو PDF، أو صورة) في سياقها الخاص، وترسل صفوفًا منظّمة بالفعل.

ضوابط أدوات الكتابة

دفاع متعدد الطبقات فوق التشغيل التجريبي، حتى لا تتسبب أي زلّة من LLM في أضرار جسيمة:

• حدود قصوى لحجم كل استدعاء. تفرض أدوات كتابة MCP حدًّا أصغر بكثير من نقاط نهاية مستورد Excel الأساسية: 200 بطاقة لـ create_cards_bulk / update_cards_bulk / archive_cards، و500 عملية لـ upsert_relations_bulk. وهو حدّ كبير بما يكفي لأي رفع مُخرج واقعي مفرد، وصغير بما يكفي ليظل بالإمكان فحص معاينة التشغيل التجريبي. أما نقاط النهاية في الواجهة الخلفية نفسها فتقبل حتى 2000/5000 لمستورد Excel الشرعي في واجهة الويب.
• رمز تأكيد فوق العتبة. يجب أن تُعيد عمليات التنفيذ التي تمسّ أكثر من MCP_BATCH_CONFIRMATION_THRESHOLD صفًا (القيمة الافتراضية 20) رمز confirm_token الصادر عن التشغيل التجريبي السابق. ويُفرض ذلك بواسطة غلاف MCP والواجهة الخلفية معًا.
• لا حذف للعلاقات افتراضيًا. ترفض upsert_relations_bulk عمليات action: "delete" — ولإزالة العلاقات، استخدم الواجهة الإلكترونية حيث تُسجَّل العملية تحت هوية المستخدم مع مسار تدقيق صريح. تواصل مع الدعم لتفعيل حذف العلاقات عبر MCP لمثيلك.
• لا حذف نهائي. تتعمّد مجموعة الأدوات إغفال الحذف الدائم للبطاقات. archive_cards (حذف ناعم بنافذة استرجاع مدتها 30 يومًا) وrollback_batch هما السبيلان الوحيدان لإزالة البيانات عبر MCP، وكلاهما محكوم بالتشغيل التجريبي ومصنَّف كتدميري. وأي أداة مستقبلية تنفّذ تعديلًا لا رجعة فيه تتطلب مناقشة RFC أولًا.
• مفتاح الإيقاف. يوقف MCP_WRITES_ENABLED=false جميع أدوات الكتابة السبع عشرة دون إعادة نشر الشيفرة. وتظل أدوات القراءة الثلاثون تعمل.
• وسم مصدر التدقيق. يحمل كل طلب من خادم MCP إلى الواجهة الخلفية ترويسة X-Canopy-Origin: mcp (مُدرَجة ضمن قائمة بيضاء على جانب الخادم تقتصر على {mcp, web, api} — وتُسقَط أي قيمة أخرى). وتُوسَم الأحداث المنبثقة من تلك الطلبات بـ origin: "mcp" في حمولة سجل التدقيق، بحيث يمكن للمسؤولين تصفية عمليات الكتابة المدفوعة من MCP خارج المخطط الزمني. وتُمرّر ترويسة X-Canopy-Batch معرّف دفعة التعديل الحالية عبر كل استدعاء ضمن تنفيذ أداة واحد.

تُضبَط هذه الضوابط لكل مثيل على حدة؛ تواصل مع الدعم لطلب تغيير أي من القيم الافتراضية أدناه:

المتغير	القيمة الافتراضية	الأثر
MCP_WRITES_ENABLED	true	المفتاح الرئيسي لأدوات الكتابة. false ← MCP للقراءة فقط.
MCP_MAX_CARDS_PER_CALL	200	حد أقصى صارم على عدد الصفوف لكل استدعاء لِـ create_cards_bulk وupdate_cards_bulk وarchive_cards.
MCP_MAX_RELATIONS_PER_CALL	500	حد أقصى صارم على عمليات upsert_relations_bulk لكل طلب.
MCP_ALLOW_RELATION_DELETE	false	عند true، تقبل upsert_relations_bulk عمليات action: "delete".
MCP_BATCH_CONFIRMATION_THRESHOLD	20	عدد الصفوف الذي يتطلب تجاوزه أن يُعيد التنفيذ رمز confirm_token صادرًا عن تشغيل تجريبي سابق.
MCP_REQUIRE_DRYRUN_FIRST	true	عند true، تُرفض عملية التنفيذ التي تتجاوز العتبة دون تشغيل تجريبي مطابق سابق ضمن الجلسة نفسها. تواصل مع الدعم لتعطيل هذا الخيار لخطوط أتمتة موثوقة.

الموارد

URI	الوصف
turbo-ea://types	جميع أنواع البطاقات في النموذج الفوقي
turbo-ea://relation-types	جميع أنواع العلاقات
turbo-ea://dashboard	مؤشرات الأداء KPI للوحة المعلومات والإحصاءات الموجزة

المطالبات الموجّهة

المطالبة	الوصف
analyze_landscape	تحليل متعدد الخطوات: نظرة عامة على لوحة المعلومات، الأنواع، العلاقات
find_card	البحث عن بطاقة بالاسم، والحصول على التفاصيل والعلاقات
explore_dependencies	رسم خريطة لما تعتمد عليه البطاقة وما يعتمد عليها

---

الأذونات

الدور	الوصول
المسؤول	ضبط إعدادات MCP (إذن admin.mcp). قراءة + كتابة كاملة عبر MCP.
جميع المستخدمين المصادَق عليهم	وصول القراءة محكوم بـ RBAC الحالي لديهم. تتطلب أدوات الكتابة إذن الواجهة الخلفية المطابق للإجراء الذي تنفّذه.

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

الإذن	يحكم
inventory.create	create_cards_bulk
inventory.edit	update_cards_bulk، وانتقالات دورة الحياة/الحالة عبر transition_card_lifecycle
inventory.approval_status	انتقالات الموافقة (approve / reject / reset) عبر transition_card_lifecycle
inventory.archive	archive_cards
relations.manage	upsert_relations_bulk
diagrams.manage	create_diagram، update_diagram
bpm.edit	import_bpmn (الصياغة)؛ ويتطلب النشر إضافةً إلى ذلك إذن card.approval_status على العملية، عبر دور صاحب المصلحة process_owner، أو دور admin، أو bpm_admin
risks.manage	create_risks، update_risks
comments.create	add_card_comment
stakeholders.manage	assign_stakeholders
soaw.create	create_soaw
adr.create	create_adr، update_adr
adr.sign	sign_adr
admin.events	rollback_batch(force=True) — لتجاوز تعارض التراجع مع دفعة لاحقة

يتحكم إذن admin.mcp فيمن يمكنه إدارة إعدادات MCP. وهو متاح لدور Admin فقط افتراضيًا. ويمكن منح الأدوار المخصصة هذا الإذن عبر صفحة إدارة الأدوار.

تتدهور أداء عدة أدوات كتابة بسلاسة بدلًا من الفشل الصريح عندما يفتقر المستدعي إلى الإذن اللازم: تُعيد كل من transition_card_lifecycle وsign_adr استجابة pending مع رابط مباشر إلى الواجهة الإلكترونية، بحيث يمكن لشخص يملك الإذن الصحيح إتمام الإجراء هناك.

---

الأمان

• مصادقة مفوّضة إلى SSO: يصادق المستخدمون عبر مزوّد SSO المؤسسي لديهم. ولا يرى خادم MCP كلمات المرور أو يخزّنها قط (في وضع HTTP).
• OAuth 2.1 مع PKCE: يستخدم تدفّق المصادقة آلية Proof Key for Code Exchange (S256) لمنع اعتراض رمز التفويض.
• RBAC لكل مستخدم: يُشغَّل كل استعلام عبر MCP — قراءةً أو كتابةً — بأذونات المستخدم المصادَق عليه. ولا توجد حسابات خدمة مشتركة.
• التشغيل التجريبي افتراضيًا على عمليات الكتابة: تتخذ أدوات الكتابة افتراضيًا معاينة تحقّق-وتراجع. ويجب على أداة الذكاء الاصطناعي أن تستدعي مرة أخرى صراحةً بـ dry_run=false قبل حفظ أي شيء، ويُدقَّق كل تغيير تحت هوية المستخدم كجزء من دفعة تعديل.
• بوابة رمز التأكيد على عمليات التنفيذ الكبيرة: تتطلب عمليات التنفيذ التي تتجاوز عتبة الصفوف القابلة للضبط رمزًا صادرًا عن تشغيل تجريبي سابق، يتحقق منه غلاف MCP والواجهة الخلفية كلٌّ على حدة.
• مسار تدقيق كامل مع إمكانية التراجع: تعيد get_change_history بناء فرق أي دفعة انطلاقًا من معرّفها؛ وتستطيع rollback_batch عكس أنواع الأحداث المدعومة في دفعة ما، وتُسجَّل هذه العملية نفسها كدفعة جديدة قابلة للتدقيق.
• لا تحليل للملفات في MCP: لا يقبل خادم MCP نفسه ملفات PDF أو Excel أو الصور أو غيرها من المُخرجات الثنائية. فأداة الذكاء الاصطناعي المُستدعِية تحلّلها في سياقها الخاص وترسل صفوفًا منظّمة. يبقي هذا سطح الهجوم ضيّقًا ويتجنّب تعريض الخادم لمدخلات ثنائية مشوّهة.
• لا حذف نهائي عبر MCP: الحذف الدائم للبطاقات غير متاح كأداة. والمساران الوحيدان لإزالة البيانات هما archive_cards (حذف ناعم قابل للاسترجاع خلال 30 يومًا) وrollback_batch.
• تدوير الرموز: تنتهي صلاحية رموز الوصول بعد ساعة واحدة، ويُعاد تحديثها استباقيًا. وتدوم رموز التحديث 30 يومًا. ورموز التفويض أحادية الاستخدام وتنتهي صلاحيتها بعد 10 دقائق.
• منفذ داخلي فقط: تكشف حاوية MCP المنفذ 8001 على شبكة Docker الداخلية فقط. ويمرّ كل وصول خارجي عبر وكيل Nginx العكسي.
• مخزن رموز أحادي المثيل: تُحفظ رموز OAuth في الذاكرة داخل حاوية MCP. فإن كنت تشغّل عدة نسخ متماثلة خلف موازن حِمل، ثبّت الجلسات على مثيل واحد أو توقّع اضطرار المستخدمين إلى إعادة المصادقة بعد أي تبديل طارئ — إذ لا تُشارَك الرموز بين النسخ.

---

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

المشكلة	الحل
مفتاح MCP معطّل في الإعدادات	يجب إعداد SSO أولًا. انتقل إلى علامة التبويب Settings > Authentication وأعدّ مزوّد SSO.
ظهور "host not found" في سجلات Nginx	يشير هذا إلى أن خدمة MCP غير قابلة للوصول على مثيلك — تواصل مع الدعم.
فشل ردّ نداء OAuth	تحقق من أنك أضفت https://your-domain.example.com/mcp/oauth/callback كعنوان URI لإعادة التوجيه في تسجيل تطبيق SSO لديك.
تعذّر اتصال أداة الذكاء الاصطناعي	تحقق من أن عنوان URL لخادم MCP المعروض في الإعدادات يطابق العنوان الذي تستخدمه أداة الذكاء الاصطناعي، وأنه قابل للوصول من جهاز المستخدم.
حصول المستخدم على نتائج فارغة	يحترم MCP أذونات RBAC. فإن كان للمستخدم وصول مقيّد، فلن يرى سوى البطاقات التي يسمح بها دوره.
إعادة أداة كتابة القيمة writes_disabled	الكتابة معطّلة حاليًا على هذا المثيل. تظل أدوات القراءة تعمل؛ تواصل مع الدعم لإعادة تفعيل الكتابة عند الحاجة.
رفض التنفيذ مع رسالة confirm_token_required	الدفعة تتجاوز عدد صفوف MCP_BATCH_CONFIRMATION_THRESHOLD. أعد التشغيل بـ dry_run=true أولًا، ثم مرّر confirm_token المُعاد في استدعاء التنفيذ.
انقطاع الاتصال بعد ساعة واحدة	ينبغي لأداة الذكاء الاصطناعي معالجة تحديث الرمز تلقائيًا. وإن لم تفعل، أعد الاتصال.