أصبح بإمكان مسؤولي Promo Core الآن إدارة محتوى مواقعهم بمجرد التحدث إلى Claude أو ChatGPT أو Cursor. لم يعودوا بحاجة إلى التنقل بين صفحات الـ Dashboard، ولا يحصل الـ AI أبداً على صلاحيات أكثر من صلاحيات المسؤول الذي قام بربطه.

هذا المقال متابعة لعرضي التقديمي عن MCP. يشرح ما هو MCP، ولماذا أضفناه إلى Promo Core، وكيف يعمل من جهة المسؤول ومن جهة الـ Backend، وكيف نحافظ على أمانه. وفي النهاية أضفت بعض الدروس التي تعلمناها أثناء بنائه ولم يتسع لها وقت العرض.

ما هو MCP

MCP (Model Context Protocol) هو معيار مفتوح يتيح لتطبيقات الذكاء الاصطناعي (AI) استخدام أنظمة خارجية على شكل Tools. أطلقته Anthropic في نوفمبر 2024، وأصبح اليوم مدعوماً في Claude وChatGPT وCursor وVS Code.

الـ Model وحده لا يستطيع سوى كتابة النصوص. يمكنه أن يكتب لك مسودة مقال، لكن عليك نسخها إلى الـ Dashboard بنفسك. أما مع MCP فيستطيع الـ AI تنفيذ إجراءات حقيقية، مثل إنشاء ذلك المقال كمسودة مباشرة في الـ CMS.

قبل MCP كان لكل تطبيق AI نظام Plugins خاص به، لذلك كان لا بد من ربط كل Tool مع كل تطبيق على حدة. أما مع معيار موحد، فنكتب Server واحداً يعمل مع كل التطبيقات التي تدعم MCP. ولهذا يُشبَّه كثيراً بمنفذ USB-C للـ AI.

هناك ثلاثة أطراف:

• الـ Model (عقل Claude أو ChatGPT): يقرأ طلب المستخدم ويقرر ما يجب فعله، لكنه لا يستطيع إرسال طلبات عبر الشبكة بنفسه.
• تطبيق الـ AI (Claude.ai وChatGPT وCursor): هو الـ MCP Client، وهو من يرسل الطلبات الفعلية إلى الـ Server نيابةً عن الـ Model.
• الـ MCP Server الخاص بنا: ينشر قائمة الـ Tools المتاحة وينفذها عند الطلب.

لكل Tool اسم (مثل create_article) ووصف بلغة بسيطة والمدخلات التي يحتاجها. الـ Model لا يرى الكود أبداً، بل يقرأ هذه الأوصاف فقط ويختار الـ Tool المناسب، لذلك فإن كتابة أوصاف جيدة جزء كبير من العمل.

يُستخدم MCP في مجالات أوسع بكثير من إدارة المحتوى: يربطه المطورون بالـ Repositories والـ CI، وتربطه الشركات بـ Jira وSlack وNotion، وتستخدمه فرق الدعم لجلب الـ Tickets وصياغة الردود. أما حالتنا فهي إدارة المحتوى.

لماذا أضفناه إلى Promo Core

أعطينا الـ CMS واجهة جديدة، لا Backend جديداً. وكانت هناك أربعة أسباب لذلك:

• عمل أسرع على المحتوى. يصف المسؤول ما يريده بلغة طبيعية ("أضف سؤالاً شائعاً عن مدة التوصيل بالعربية والإنجليزية") بدلاً من تعبئة النماذج حقلاً حقلاً.
• نفس البيانات. يمر الـ AI عبر نفس الـ NestJS Services التي يستخدمها الـ Dashboard، فلا يوجد نظام ثانٍ يحتاج إلى صيانة، ولا تختلف البيانات بين المكانين.
• نفس الصلاحيات. يعمل الـ AI بهوية المسؤول الذي ربطه، وليس كمستخدم بصلاحيات كاملة، ولا يستطيع فعل إلا ما يستطيع هذا المسؤول فعله في الـ Dashboard.
• كل عميل يحصل عليه. Promo Core هو White-label Starter ننسخه لكل عميل، لذلك يحصل كل مشروع جديد على CMS جاهز للعمل مع الـ AI منذ البداية.

كيف يعمل من جهة المسؤول

يستغرق الربط حوالي دقيقة ويتم مرة واحدة فقط. بعدها يكفي أن يتحدث المسؤول مع الـ AI.

1. الربط (Connect). يضيف المسؤول Connector جديداً في Claude أو ChatGPT ويلصق رابط الـ MCP الخاص بنا. تعرض صفحة Connectors في الـ Dashboard هذا الرابط، مع دليل خطوة بخطوة لكل من Claude وChatGPT وCursor. وعندما يحاول Claude الاتصال لأول مرة، يرد الـ Backend بأنه غير مصرح له ويخبره أين يسجل الدخول.
2. الموافقة (Consent). يفتح Claude صفحة الموافقة في الـ Dashboard. يسجل المسؤول الدخول بحسابه المعتاد في Promo Core، ويرى أي تطبيق يطلب الوصول، ثم يضغط Approve. إنها نفس طريقة "Sign in with…" المألوفة (والمعيار الذي تعتمد عليه اسمه OAuth)، لذلك لا يعطي المسؤول كلمة المرور لـ Claude أو ChatGPT أبداً.
3. الـ Token. يمنح الـ Backend تطبيق الـ AI ما يسمى MCP Token. يمكن تشبيهه ببطاقة غرفة الفندق: لا يفتح إلا باب /mcp، ولا يمكن استخدامه لتسجيل الدخول إلى الـ Dashboard، وتنتهي صلاحيته ويتجدد تلقائياً.
4. الـ Tools. من الآن فصاعداً، ومع كل رسالة، يطلب تطبيق الـ AI من الـ Server قائمة الـ Tools المسموح بها لهذا المسؤول. يختار الـ Model واحداً منها ويعبئ مدخلاته ويرسل الطلب مع الـ Token. يتحقق الـ Backend من الطلب وينفذه، ثم يخبر الـ AI المسؤول بما قام به.

إليك كيف يبدو ذلك عملياً:

لا يحتاج المسؤول إلى معرفة أسماء هذه الـ Tools. يُنشأ المحتوى الجديد كمسودة (Draft) بشكل افتراضي، لذلك يراجعه شخص قبل نشره، ويبقى النشر دائماً خطوة منفصلة وصريحة.

ما يحدث في الـ Backend

طبقة MCP هي باب جديد إلى الـ NestJS Backend الحالي، وليست Backend ثانياً. ينتهي كل من الـ Dashboard والـ AI إلى استدعاء نفس الـ Service Methods، بنفس الـ Validation ونفس فحوصات الصلاحيات. الفرق فقط في المدخل (/api/admin/... مع Dashboard Token، أو /mcp مع MCP Token)، وفي من يقرر ما الذي يُستدعى: شخص يضغط الأزرار، أو Model يقرأ قائمة الـ Tools.

مساران وBackend واحد

• مسار الـ Dashboard: المسؤول يضغط Save ← /api/admin/... مع Dashboard Token ← الـ Validation وفحص الصلاحيات.
• مسار الـ AI: Claude أو ChatGPT أو Cursor ← POST /mcp مع MCP Token يتحقق منه McpAuthGuard ← createMcpServer(userId) مع الـ Tools التي يسمح بها دور المستخدم فقط ← الـ Validation وفحص الصلاحيات.
• الجزء المشترك: الـ NestJS Services الحالية (مثل articleService.create()) ← Prisma ← PostgreSQL.

الخطوة الإضافية الوحيدة في مسار الـ AI هي إنشاء MCP Server خاص بكل مسؤول. ومن فحص الصلاحيات فما دون، ينفذ المساران نفس الكود.

يمر استدعاء الـ Tool الواحد بخمس خطوات:

1. POST /mcp. كل شيء يمر عبر Endpoint واحد، مبني باستخدام الـ MCP TypeScript SDK الرسمي مع Streamable HTTP Transport. واستدعاء الـ Tool هو مجرد HTTP POST عادي يحمل JSON-RPC Body.
2. McpAuthGuard. تتحقق Passport Strategy مخصصة من الـ Token: يجب أن يكون الـ Audience هو رابط الـ MCP الخاص بنا، وأن يتضمن الـ Scope القيمة mcp، وأن يطابق mcpTokenVersion القيمة الحالية للمستخدم في قاعدة البيانات.
3. createMcpServer(userId). ننشئ MCP Server جديداً لهذا المسؤول، ونسجل فيه فقط الـ Tools التي يسمح بها دوره. وإذا لم تكن لديه صلاحية الحذف، فلا تُسجَّل Tools الحذف أصلاً، ولا يعرف الـ AI بوجودها.
4. الـ Tool Handler. يتم التحقق من المدخلات مرتين: مرة عبر Zod Schema (وهو نفسه شكل المدخلات الذي يراه الـ AI)، ومرة عبر نفس الـ class-validator DTO الذي يستخدمه الـ Admin Controller. بعد ذلك يتحقق permissionService.assert() من الصلاحية المطلوبة، مثل CREATE_ARTICLE.
5. الـ Service الحالي. يستدعي الـ Handler نفس الـ Method التي يستخدمها الـ Dashboard، مثل articleService.create()، والتي تكتب في PostgreSQL عبر Prisma.

لماذا ننشئ Server جديداً لكل Request

كان هذا أكثر سؤال طُرح بعد العرض، وهناك ثلاثة أسباب:

• قائمة الـ Tools شخصية. يحمل الـ MCP Server قائمة Tools واحدة. ولو استخدمنا Server مشتركاً لرأى كل المسؤولين نفس الـ Tools، بما فيها ما لا يُسمح لهم باستخدامه. كما يحتفظ كل Tool Handler بالـ userId الذي أُنشئ به، فلا يمكن أن يتسرب أي شيء بين المستخدمين.
• الـ SDK يتطلب ذلك في الـ Stateless Mode. نشغّل الـ Transport بدون Sessions (sessionIdGenerator: undefined). وفي هذا الوضع يتوقع الـ SDK إنشاء Server جديد لكل Request، لأن عميلين قد يرسلان نفس الـ JSON-RPC Message ID في الوقت نفسه، فتتعارض الرسائل على Server مشترك.
• الـ Stateless هو ما نريده أصلاً. يمكن لأي Instance من الـ Backend الرد على أي Request، فنستطيع التوسع دون الحاجة إلى Sticky Sessions. وتُطبَّق تغييرات الصلاحيات من الـ Request التالي مباشرة. كما يُغلق الـ Server والـ Transport عند انتهاء الـ Response، فلا يتراكم شيء في الذاكرة.

إنشاء الـ Server عملية خفيفة، لأن تسجيل الـ Tools ينشئ Objects في الذاكرة فقط. أما التكلفة الحقيقية فهي بعض الاستعلامات من قاعدة البيانات لفحص الصلاحيات، وهذا مقبول تماماً بحجم استخدام الـ AI الحالي.

أكثر من 200 Tool من Config واحد لكل Module

لم نكتب كل Tool يدوياً. كل Content Module موصوف بـ Config Object واحد، ويحوّله Registrar عام إلى ما يصل إلى سبعة Tools: list وget وcreate وupdate وpublish وunpublish وdelete.

{
  resource: 'article',
  permissions: { view, create, update, delete },
  service: articleService,
  createSchema, updateSchema,
  publishField: 'published',
}

هناك 26 Module مُعرّفة بهذه الطريقة، ما ينتج ما يصل إلى 174 Tool. وهناك حوالي 90 Tool أخرى مكتوبة يدوياً للعمليات التي ليست مجرد CRUD: رفع الـ Media، وإصدارات الـ Forms، والـ Email Templates، والـ Push Notifications، والأدوار والمسؤولين، والإعدادات، والـ Import/Export Jobs. وإضافة Content Module جديد إلى MCP تقتصر في الغالب على إضافة الـ Config والـ Schemas الخاصة به.

الأمان

يحصل الـ AI على الصلاحيات التي يمنحها له المسؤول بالضبط، ويستطيع المسؤول سحبها في أي وقت. وهناك أربع ضمانات تحقق ذلك:

كما نضيف عبر الـ Seeder دوراً باسم AI Editor يملك صلاحيات العرض والإنشاء والتعديل على المحتوى، دون أي صلاحية حذف. ربط الـ AI بهذا الدور يعني أنه يستطيع كتابة المسودات وتعديلها، لكنه لا يستطيع حذف أي شيء. والـ Tools التي تحذف مُعلَّمة على أنها Destructive، حتى تتمكن تطبيقات الـ AI من طلب تأكيد المستخدم قبل استدعائها. كما تُسجَّل استدعاءات الـ Tools في الـ Logs مع اسم الـ Tool والـ User ID.

كيف نحمي قاعدة البيانات

لا يتعامل الـ AI مع قاعدة البيانات مباشرة أبداً. كل ما يستطيعه هو استدعاء نفس الدوال التي تستدعيها واجهتنا، ويمر كل استدعاء عبر نفس الطبقات التي يمر بها Request الـ Dashboard:

1. Zod Validation يتحقق من شكل المدخلات وأنواعها قبل تنفيذ أي شيء.
2. فحص الصلاحيات يتأكد من أن دور المسؤول يسمح بهذا الإجراء.
3. الـ NestJS Services تطبق نفس الـ Business Rules المطبقة في الـ Dashboard.
4. Prisma يتعامل مع PostgreSQL باستخدام Parameterized Queries فقط.

لا تحتوي طبقة MCP على أي Raw SQL إطلاقاً، فلا يوجد Query String يمكن استهدافه بـ SQL Injection. كما أنها لا تحتوي على أي Business Logic خاص بها. وعندما يصلح أحدهم Bug أو يضيف قاعدة جديدة في أحد الـ Services، يحصل كل من الـ Dashboard والـ AI على التغيير تلقائياً.

دروس من بناء المشروع

لم يتسع لها وقت العرض، لكنها ستفيد كل من يبني MCP Server.

• أوصاف الـ Tools هي Prompts. يختار الـ Model الـ Tools بناءً على أسمائها وأوصافها فقط، لذلك نكتبها موجهة للـ Model. مثلاً، يمكن أن يقول الوصف: "call list_options first to get valid category types"، وعندها يبحث الـ AI عن القيم الصحيحة بنفسه بدلاً من التخمين.
• اجعل الـ Responses صغيرة. كل ما يعيده الـ Tool يدخل في الذاكرة العاملة المحدودة للـ AI (الـ Context Window). لذلك تعيد Tools القوائم نتائج مختصرة، وكل Response محدود بحوالي 12,000 حرف.
• أعِد رسائل خطأ مفهومة. عندما يفشل الـ Validation أو فحص الصلاحيات، يتلقى الـ AI رسالة واضحة بدلاً من Crash، وفي أغلب الأحيان يصحح مدخلاته ويعيد المحاولة بنفسه.
• المسودة أولاً، ثم النشر بشكل صريح. إنشاء المحتوى كمسودة يُبقي شخصاً في الحلقة قبل نشر أي شيء.
• أعِد استخدام طبقة الـ Services. أهم قرار اتخذناه هو عدم كتابة أي Database Logic أو Business Logic داخل طبقة MCP. هذا أبقى الميزة صغيرة، ويمنعها من الاختلاف عن الـ Dashboard مع الوقت.

خطوات مقترحة للمستقبل

• تحميل الصلاحيات مرة واحدة لكل Request. حالياً، كل فحص صلاحية يعيد تحميل المستخدم من قاعدة البيانات. وتخزين قائمة الصلاحيات مؤقتاً (Caching) طوال مدة الـ Request سيلغي معظم هذه الاستعلامات إذا زاد استخدام الـ AI.
• جعل AI Editor الدور الافتراضي للـ Connectors. تشجيع المسؤولين على ربط الـ AI بحساب مخصص بدون صلاحيات حذف يجعل الإعداد الآمن هو الإعداد الأسهل.

الخلاصة

MCP جسر آمن بين الـ AI والـ CMS الخاص بنا. يعمل الـ AI بهوية المسؤول الذي ربطه، وبموافقته وصلاحياته، ويمكن سحب الوصول في أي وقت. وهو ليس CMS ثانياً، بل يستخدم نفس الـ Services ويتبع نفس القواعد.

لتجربته، افتح صفحة Connectors في Promo Core Dashboard واتبع الدليل الخاص بـ Claude أو ChatGPT أو Cursor. ويسعدني تلقي أسئلتكم وأفكاركم في أي وقت.