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

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

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

---

كيف يعمل

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

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

---

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

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

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

---

الإعداد

الخطوة 1: تشغيل خدمة MCP

خادم MCP هو ملف اختياري في Docker Compose. أضف --profile mcp إلى أمر بدء التشغيل:

docker compose --profile mcp up --build -d

يؤدي هذا إلى تشغيل حاوية Python خفيفة (المنفذ 8001، داخلي فقط) إلى جانب الواجهة الخلفية والواجهة الأمامية. ويوجّه Nginx طلبات /mcp/ إليها تلقائيًا.

الخطوة 2: ضبط متغيرات البيئة

أضف هذه المتغيرات إلى ملف .env لديك:

TURBO_EA_PUBLIC_URL=https://your-domain.example.com
MCP_PUBLIC_URL=https://your-domain.example.com/mcp

المتغير	القيمة الافتراضية	الوصف
TURBO_EA_PUBLIC_URL	http://localhost:8920	عنوان URL العام لمثيل Turbo EA لديك
MCP_PUBLIC_URL	http://localhost:8920/mcp	عنوان URL العام لخادم MCP (يُستخدم في عناوين URI لإعادة توجيه OAuth)
MCP_PORT	8001	المنفذ الداخلي لحاوية MCP (نادرًا ما يحتاج إلى تغيير)

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

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

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

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

الخطوة 4: تفعيل 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": {
    "turbo-ea": {
      "type": "http",
      "url": "https://your-domain.example.com/mcp/mcp"
    }
  }
}

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

---

الاختبار المحلي (وضع stdio)

للتطوير أو الاختبار المحلي دون SSO/HTTPS، يمكنك تشغيل خادم MCP في وضع stdio — حيث يشغّله Claude Desktop مباشرةً كعملية محلية.

1. ثبّت حزمة خادم MCP:

pip install ./mcp-server

2. أضف ما يلي إلى ملف إعداد Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "turbo-ea": {
      "command": "python",
      "args": ["-m", "turbo_ea_mcp", "--stdio"],
      "env": {
        "TURBO_EA_URL": "http://localhost:8000",
        "TURBO_EA_EMAIL": "[email protected]",
        "TURBO_EA_PASSWORD": "your-password"
      }
    }
  }
}

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

---

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

يعرض خادم MCP عدد 30 أداة موزّعة على مجموعتين: 25 أداة قراءة تستعلم عن بيانات هندسة المؤسسة، و5 أدوات كتابة تحوّل المُخرجات التي تحتفظ بها أداة الذكاء الاصطناعي في سياقها الخاص (جداول البيانات، وملفات BPMN XML، وملفات DrawIO XML، والمستندات، والصور) إلى بطاقات وعلاقات ومخططات.

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

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

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

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

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

الأداة	الوصف
search_cards	البحث في البطاقات وتصفيتها حسب النوع أو الحالة أو النص الحرّ
get_card	الحصول على التفاصيل الكاملة لبطاقة حسب UUID
get_card_relations	الحصول على جميع العلاقات المرتبطة ببطاقة
get_card_hierarchy	الحصول على أسلاف البطاقة وأبنائها
list_card_types	سرد جميع أنواع البطاقات في النموذج الفوقي
get_relation_types	سرد أنواع العلاقات، مع إمكانية التصفية حسب نوع البطاقة

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

الأداة	الوصف
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	نتائج الامتثال مجمّعة حسب اللائحة التنظيمية
get_compliance_overview	درجات الامتثال + مصفوفة الحالة لكل لائحة + بيانات وصفية لآخر فحص

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

الأداة	الوصف
list_principles	مبادئ هندسة المؤسسة المنشورة (البيان، والمبرّر، والتبعات)
list_adrs	سجلات قرارات البنية (ADR)، قابلة للتصفية حسب المبادرة/الحالة
get_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	روابط المستندات المرفقة ببطاقة

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

أدوات الكتابة — رفع المُخرجات

تتيح خمس أدوات لوكيل الذكاء الاصطناعي تحويل المُخرجات إلى بيانات هندسة مؤسسة منظّمة. يقرأ الوكيل الملف المصدر من سياقه الخاص (الرؤية متعددة الوسائط، المرفقات)، ويستخرج صفوفًا منظّمة، ويستدعي هذه الأدوات. ولا يحلّل خادم MCP نفسه الملفات قط — فهو يتوقّع مُدخلات منظّمة بالفعل.

الأداة	الوصف
create_cards_bulk	إنشاء بطاقات كثيرة في استدعاء واحد (مثل صفوف جدول بيانات). يدعم مراجع الأب بالاسم ضمن الدفعة نفسها مع ترتيب طوبولوجي على جانب الخادم.
resolve_card_refs	التحقق المسبق من المراجع المستندة إلى الأسماء قبل الاستيراد المجمّع — مفيد لإظهار الآباء الملتبسين أو المفقودين للمستخدم.
upsert_relations_bulk	إنشاء أو حذف العلاقات بين البطاقات. يجري التحقق من المصدر/الهدف/النوع مقابل النموذج الفوقي.
create_diagram	إنشاء مخطط DrawIO حرّ مع روابط اختيارية إلى بطاقات قائمة.
import_bpmn	حفظ مخطط BPMN 2.0 XML مقابل بطاقة عملية أعمال قائمة. إذا لم تطابق أي بطاقة الاسم المُعطى، تُعيد الأداة خطأ card_not_found يوجّه الوكيل إلى create_cards_bulk — يُلزم هذا الوكيل بإنشاء البطاقة صراحةً بوصف ونوع فرعي وسمات أولًا، بدلًا من اختصار يُنتج بطاقة هزيلة.

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

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

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

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

• حدود قصوى لحجم كل استدعاء. تفرض أدوات كتابة MCP حدًّا أصغر بكثير من نقاط نهاية مستورد Excel الأساسية: 200 صف لـ create_cards_bulk، و500 عملية لـ upsert_relations_bulk. كبير بما يكفي لأي رفع مُخرج واقعي مفرد، وصغير بما يكفي ليظل بالإمكان فحص معاينة التشغيل التجريبي.
• لا حذف للعلاقات افتراضيًا. ترفض upsert_relations_bulk عمليات action: "delete" — لإزالة العلاقات، استخدم الواجهة الإلكترونية حيث تُسجّل العملية تحت هوية المستخدم. يمكن للمشغّلين الاشتراك بضبط MCP_ALLOW_RELATION_DELETE=true.
• مفتاح الإيقاف. يوقف MCP_WRITES_ENABLED=false جميع أدوات الكتابة الخمس دون إعادة نشر الشيفرة. وتظل أدوات القراءة الخمس والعشرون تعمل.
• وسم مصدر التدقيق. يحمل كل طلب من خادم MCP إلى الواجهة الخلفية ترويسة X-Turbo-EA-Origin: mcp. وتُوسَم الأحداث المنبثقة من تلك الطلبات بـ origin: "mcp" في حمولة سجل التدقيق، بحيث يمكن للمسؤولين تصفية عمليات الكتابة المدفوعة من MCP خارج المخطط الزمني تمييزًا لها عن إجراءات الواجهة الإلكترونية.
• لا أدوات تدمير شامل. تتعمّد مجموعة الأدوات إغفال حذف البطاقات وأرشفتها وتحديثها المجمّع. وستتطلب إضافة أي أداة من هذا القبيل مراجعة تصميم صريحة.

متغيرات البيئة الأربعة الخاصة بالضوابط على حاوية MCP:

المتغير	القيمة الافتراضية	الأثر
MCP_WRITES_ENABLED	true	المفتاح الرئيسي لأدوات الكتابة. false ← MCP للقراءة فقط.
MCP_MAX_CARDS_PER_CALL	200	حد أقصى صارم لصفوف create_cards_bulk لكل طلب.
MCP_MAX_RELATIONS_PER_CALL	500	حد أقصى صارم لعمليات upsert_relations_bulk لكل طلب.
MCP_ALLOW_RELATION_DELETE	false	عند true، تقبل upsert_relations_bulk عمليات action: "delete".

الموارد

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

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

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

---

الأذونات

الدور	الوصول
المسؤول	ضبط إعدادات MCP (إذن admin.mcp). قراءة + كتابة كاملة عبر MCP.
جميع المستخدمين المصادَق عليهم	وصول القراءة محكوم بـ RBAC الحالي لديهم. تتطلب أدوات الكتابة أذونات الواجهة الخلفية المطابقة — inventory.create (البطاقات)، وrelations.manage (العلاقات)، وdiagrams.manage (المخططات)، وbpm.edit (BPMN).

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

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

---

الأمان

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

---

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

المشكلة	الحل
مفتاح MCP معطّل في الإعدادات	يجب إعداد SSO أولًا. انتقل إلى علامة التبويب Settings > Authentication وأعدّ مزوّد SSO.
ظهور "host not found" في سجلات Nginx	خدمة MCP لا تعمل. شغّلها بـ docker compose --profile mcp up -d. يعالج إعداد Nginx هذا بسلاسة (استجابة 502، دون تعطّل).
فشل ردّ نداء OAuth	تحقق من أنك أضفت https://your-domain.example.com/mcp/oauth/callback كعنوان URI لإعادة التوجيه في تسجيل تطبيق SSO لديك.
تعذّر اتصال أداة الذكاء الاصطناعي	تحقق من أن MCP_PUBLIC_URL يطابق العنوان القابل للوصول من جهاز المستخدم. وتأكد من عمل HTTPS.
حصول المستخدم على نتائج فارغة	يحترم MCP أذونات RBAC. فإن كان للمستخدم وصول مقيّد، فلن يرى سوى البطاقات التي يسمح بها دوره.
انقطاع الاتصال بعد ساعة واحدة	ينبغي لأداة الذكاء الاصطناعي معالجة تحديث الرمز تلقائيًا. وإن لم تفعل، أعد الاتصال.