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

يتضمّن Canopy خادم 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)
    ▼
Canopy MCP Server (:8001, internal)
    │
    │  OAuth 2.1 with PKCE
    │  delegates to your SSO provider
    ▼
Canopy Backend (:8000)
    │
    │  Per-user RBAC
    ▼
PostgreSQL

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

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

قبل تفعيل 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 -d

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

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

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

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

المتغير	القيمة الافتراضية	الوصف
`CANOPY_URL`	`http://backend:8000`	عنوان URL الداخلي للواجهة الخلفية الذي تتصل به حاوية MCP (اسم خدمة Docker — نادرًا ما يحتاج إلى تغيير).
`CANOPY_PUBLIC_URL`	`http://localhost:8920`	عنوان URL العام لمثيل Canopy لديك.
`MCP_PUBLIC_URL`	`http://localhost:8920/mcp`	عنوان URL العام لخادم MCP (يُستخدم في عناوين URI لإعادة توجيه OAuth والبيانات الوصفية).
`MCP_PORT`	`8001`	المنفذ الداخلي لحاوية MCP (نادرًا ما يحتاج إلى تغيير).

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

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

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

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

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

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

warning

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

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

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

Claude Desktop

افتح Settings > Connectors > Add custom connector.
أدخل عنوان URL لخادم MCP: https://your-domain.example.com/mcp
انقر Connect — تُفتح نافذة متصفح لتسجيل الدخول عبر SSO.
بعد المصادقة، يمكن لـ 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.

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

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

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

pip install ./mcp-server

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

{
  "mcpServers": {
    "canopy": {
      "command": "python",
      "args": ["-m", "canopy_mcp", "--stdio"],
      "env": {
        "CANOPY_URL": "http://localhost:8000",
        "CANOPY_EMAIL": "[email protected]",
        "CANOPY_PASSWORD": "your-password"
      }
    }
  }
}

في هذا الوضع، يصادق الخادم مباشرةً باستخدام البريد الإلكتروني وكلمة المرور (دون OAuth)، ويحدّث JWT الخاص بـ Canopy تلقائيًا في الخلفية.

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

يعرض خادم 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) بوصفه بيانات غير موثوقة عند قراءته لاحقًا — فلا يفسّره الخادم قط بوصفه تعليمات، بل يعرضه فقط.

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

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

يستدعي الوكيل list_card_types وget_relation_types لفهم النموذج الفوقي.
يحلّل الوكيل جدول البيانات (في سياقه الخاص، لا في MCP) ويبني قواميس صفوف.
اختياريًا، يستدعي الوكيل resolve_card_refs للتحقق من أن أي مراجع أب/علاقة مستندة إلى الاسم تُحلّ دون التباس.
يستدعي الوكيل create_cards_bulk(cards=…, dry_run=True) ويعرض المعاينة على المستخدم.
يؤكّد المستخدم؛ فيستدعي الوكيل الأداة مرة أخرى بـ dry_run=False (مع إعادة إرسال confirm_token إذا تجاوزت الدفعة عتبة التأكيد) لتنفيذ العملية.
إذا كانت أعمدة العلاقات موجودة، يستدعي الوكيل عندئذٍ 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_ALLOW_RELATION_DELETE=true.
لا حذف نهائي. تتعمّد مجموعة الأدوات إغفال الحذف الدائم للبطاقات. 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:

المتغير	القيمة الافتراضية	الأثر
`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 لا تعمل. شغّلها بـ `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. فإن كان للمستخدم وصول مقيّد، فلن يرى سوى البطاقات التي يسمح بها دوره.
إعادة أداة كتابة القيمة `writes_disabled`	تم ضبط `MCP_WRITES_ENABLED=false` على هذا النشر. تظل أدوات القراءة تعمل؛ اطلب من أحد المشغّلين إعادة تفعيل الكتابة عند الحاجة.
رفض التنفيذ مع رسالة `confirm_token_required`	الدفعة تتجاوز عدد صفوف `MCP_BATCH_CONFIRMATION_THRESHOLD`. أعد التشغيل بـ `dry_run=true` أولًا، ثم مرّر `confirm_token` المُعاد في استدعاء التنفيذ.
انقطاع الاتصال بعد ساعة واحدة	ينبغي لأداة الذكاء الاصطناعي معالجة تحديث الرمز تلقائيًا. وإن لم تفعل، أعد الاتصال.

كيف يعمل​

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

الإعداد​

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

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

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

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

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

Claude Desktop​

VS Code (GitHub Copilot / Cursor)​

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

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

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

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

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

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

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

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

الموارد​

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

الأذونات​

الأمان​

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