ربط عملاء MCP بأمان

يوفّر Nibleaf نقطة MCP مصادَقًا عليها عبر HTTP في /api/mcp، وهي معطّلة افتراضيًا. يرتبط كل مفتاح بمشروع واحد، ويحمل نطاقات صريحة، وله تاريخ انتهاء، ويمكن لمسؤول المشروع إلغاؤه أو تدويره ذريًا. يشتق الخادم المشروع والمؤسسة من المفتاح؛ ولا تقبل الأدوات أيًا منهما كسلطة يحددها المتصل.

السطح الأولي للقراءة فقط، باستثناء preview_theme_import الذي يتحقق من السمة ويعرض معاينتها من دون كتابة حالة المشروع. لا تتوفر عمليات النشر أو الحذف أو بيانات اعتماد المزوّد أو الدفع أو بدائيات قاعدة البيانات أو الوصول العشوائي للملفات أو تنفيذ الشيفرة.

تفعيل نقطة النهاية

اضبط بيئة خدمة API:

MCP_ENABLED=true
MCP_ALLOWED_HOSTS=mcp.docs.example.com
MCP_RATE_LIMIT_PER_MIN=120

تُسمح أسماء المضيفين في API_URL وAPP_URL دائمًا. أضف إلى MCP_ALLOWED_HOSTS أسماء المضيفين العامة الإضافية فقط؛ ولا تضف بروتوكولًا أو مسارًا أو معلومات مستخدم أو فاصلة داخل المضيف الواحد أو قيمة بحرف بدل. أعد إنشاء خدمة API بعد التغيير.

تتحقق نقطة النهاية من Host وOrigin وX-Forwarded-Host و X-Forwarded-Proto قبل المصادقة. اضبط الوكيل العام ليستبدل ترويسات التمرير غير الموثوقة ويمرر مضيفًا وبروتوكولًا واحدين واضحين. أبقِ MCP معطّلًا إلى أن يعيد مسار TLS والوكيل العام اسم المضيف المتوقع.

إنشاء مفتاح مرتبط بالمشروع

سجّل الدخول عبر Better Auth، ثم افتح الإعدادات ← مفاتيح API للمشروع، واختر نطاقات القراءة المطلوبة فقط وتاريخ الانتهاء، ثم أنشئ المفتاح. تتطلب كل مسارات دورة حياة المفتاح دور ADMIN أو OWNER في المشروع. يظهر السر مرة واحدة؛ خزّنه في مخزن أسرار العميل، لا في التحكم بالمصدر أو سجل الطرفية أو رسائل الدعم أو السجلات أو لقطات الشاشة أو إعداد MCP محفوظ في مستودع.

يحتاج كل مفتاح MCP إلى mcp:connect. لا يتحكم النطاق إلا في سطحه المسمى ولا يوسّع ارتباط المفتاح بالمشروع. يعرض اكتشاف الإمكانات الأدوات والموارد المسجلة للمفتاح نفسه. لا تفترض توفر إمكانية مستقبلية موثقة إذا لم تظهر في tools/list أو nibleaf://capabilities.

لا تستطيع مفاتيح حرف البدل القديمة الاتصال عمدًا. يظهر المفتاح ذو تاريخ انتهاء فارغ أو من دون mcp:connect أو بحالة ترحيل قديمة على أنه يحتاج إلى التدوير. دوّره إلى مجموعة نطاقات صريحة ومنتهية بدل تعديل صف قاعدة البيانات.

ضبط العميل

استخدم المصدر العام لواجهة API ومرّر المفتاح كرمز Bearer. غالبًا ما يقبل عميل يدعم خوادم MCP البعيدة عبر HTTP إعدادًا بهذا الشكل:

{
  "mcpServers": {
    "nibleaf": {
      "url": "https://api.docs.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${NIBLEAF_MCP_API_KEY}"
      }
    }
  }
}

تختلف أسماء إعدادات العملاء. استخدم خيار HTTP أو الخادم البعيد، لا أمرًا محليًا ولا موصل ملفات. مرّر NIBLEAF_MCP_API_KEY عبر آلية الأسرار التي يدعمها العميل. استدعِ أولًا tools/list ثم get_capabilities. تحتوي الاستجابة الناجحة على محتوى بروتوكول MCP وغلاف منظم يضم معرّف الطلب ومعرّف المشروع المرتبط والإمكانية المطلوبة.

حد الإمكانات الحالي

مورد الإمكانات هو المرجع النهائي. يشمل السطح المستقر في هذا الإصدار بيانات المشروع؛ وبيانات الصفحات ومحتواها المؤلف؛ واللغات والإصدارات؛ وتحليلات مجمعة من دون عبارات البحث؛ وإعدادات البحث وتشخيص الفهرس الخالي من المحتوى؛ وملخصات الاستخدام الدقيقة والاستحقاقات الإرشادية؛ وقراءة كتالوج الإضافات وحالتها وسجلها؛ وبيانات قالب السمة وكتالوجها الآمنة ومعاينة الاستيراد من دون كتابة؛ وملخصات منقحة للتصدير والنشر؛ وبيانات تغييرات النشر المعلّقة؛ وكتالوج التكاملات وحالات الاتصال وGit المنقحة والمطابقة للحقيقة.

نطاقات المجالات القابلة للإصدار حاليًا هي search:read وusage:read و entitlements:read وaddons:read وthemes:read وintegrations:read، إضافة إلى نطاقات قراءة المشروع والصفحات واللغات والإصدارات والتحليلات والتصدير والنشر. لا يصدر هذا الإصدار أي نطاق كتابة جديد للمجالات، ولا usage:export، ولا نطاق إعادة فهرسة البحث أو تحقق التكاملات أو حذفها أو بيانات الاعتماد أو الدفع. ويبقى exports:read سطح قراءة مستقلًا لملخصات مهام التصدير المنقحة.

تستخدم موارد المشروع عناوين مرتبطة مثل:

nibleaf://projects/{boundProjectId}
nibleaf://projects/{boundProjectId}/pages
nibleaf://projects/{boundProjectId}/pages/{pageId}
nibleaf://projects/{boundProjectId}/languages
nibleaf://projects/{boundProjectId}/versions
nibleaf://projects/{boundProjectId}/search/configuration
nibleaf://projects/{boundProjectId}/usage
nibleaf://projects/{boundProjectId}/entitlements
nibleaf://projects/{boundProjectId}/addons
nibleaf://projects/{boundProjectId}/theme-catalog
nibleaf://projects/{boundProjectId}/theme-template
nibleaf://projects/{boundProjectId}/integrations
nibleaf://projects/{boundProjectId}/deployments/latest

يعيد معرّف مشروع مختلف أو صفحة خارج المشروع المرتبط نتيجة عدم العثور نفسها التي يعيدها مورد غير موجود. تحذف إسقاطات القراءة حمولات المزوّد وعناوين معاينة Bearer ومفاتيح التخزين والبصمات ولقطات النشر وحالة نظام ملفات السمة والأخطاء الخام وبيانات الاعتماد وعبارات البحث التحليلية. تعرض تشخيصات البحث بيانات المخطط والمراجعة والنموذج المنطقية، لكنها لا تعرض المجموعات المادية أو المحتوى أو المتجهات أو البصمات أو حمولات المزوّد الخام. تبقى كميات الاستخدام وحدوده سلاسل عشرية دقيقة أو null؛ ولا تتحول البيانات الجزئية أو غير المتاحة إلى صفر، كما يبقى سلوك الحظر المضبوط إرشاديًا فقط. يتضمن نطاق pages:read المحتوى المؤلف داخل المشروع المرتبط الواحد؛ فلا تمنحه إلا إذا احتاج العميل إلى نصوص المستندات.

تشغيل التدقيق وتحديد المعدل

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

يمثل MCP_RATE_LIMIT_PER_MIN حماية محدودة لكل مفتاح ولكل عملية API، وليس حدًا شاملًا للنشر بين النسخ. طبّق حدًا شاملًا عند بوابة الدخول الموثوقة أو الحافة المشتركة، وراقب HTTP 429 وRetry-After وترويسات X-RateLimit-*. لا تصف عداد عملية واحدة بأنه الحصة الشاملة للعميل. ولتقييد تضخّم كتابات التدقيق، يسجّل النقل رفض transport_rate_limit واحدًا لكل مفتاح ونافذة بدل إضافة صف لكل استجابة 429 متكررة.

التدوير والإلغاء والتراجع

يلغي التدوير المفتاح القديم ذريًا وينشئ مفتاحًا جديدًا منتهيًا. حدّث العميل بالسر الذي يظهر مرة واحدة، وتحقق من tools/list، ثم احذف السر القديم من مخزنه. الإلغاء غير قابل للعكس ويتطلب مربع تأكيد في لوحة التحكم، ويسري في الطلب التالي. لا تُعد تمكين مفتاح مسرّب بسبب وجود نسخة احتياطية لقاعدة البيانات.

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

قبل التراجع عن التطبيق، عطّل MCP وأوقف عملاءه. لا تنفذ rollback.sql الخاص بترحيل MCP بعد نجاح ترحيل Prisma. انشر تطبيقًا لا يقرأ بيانات تدقيق MCP أو أعمدة مصدر مفاتيح API التي يملكها MCP، ثم انشر عبارات الرجوع المراجعة بوصفها ترحيلًا تقدميًا لاحقًا وبترتيب الاعتماد العكسي. استخدم عبارات التراجع في المستودع مباشرة فقط لعكس ترحيل فاشل طُبّق جزئيًا؛ وبعد عكس العبارات الجزئية بأمان، علّم الترحيل الفاشل كمتراجع عنه وأعد تشغيل الترحيل التقدمي المصحح. انسخ سجلات التدقيق احتياطيًا أولًا إذا كانت سياسة الاحتفاظ تتطلبها.

لأن MCP هو الترحيل التابع الأخير، عطّله واعكسه قبل مخطط التكاملات. اتبع الترتيب العكسي كاملًا في دليل ترحيل الإصدار المجمع.

استكشاف الأعطال بأمان

• 503 mcp:disabled: فعّل MCP في خدمة API وأعد إنشاءها.
• 400 mcp:invalid_request: صحح تمرير المضيف أو المصدر المشوّه أو الملتبس.
• 401 auth:invalid_api_key: استبدل المفتاح المشوّه أو المنتهي أو الملغى أو الخالي من تاريخ الانتهاء.
• 403 auth:insufficient_scope: دوّر المفتاح مع mcp:connect ونطاق القراءة الدقيق.
• خطأ مورد 404: تحقق من أن العنوان يستخدم مشروع المفتاح المرتبط وموردًا داخله.
• 429 http:rate_limited: التزم بـRetry-After وافحص حدود البوابة والعملية المحلية.
• 503 storage:error: أعد خدمة حفظ التدقيق قبل المحاولة؛ فالقراءة لا تُبلّغ كناجحة دون حدث تدقيق.

اربط الأعطال بمعرّف الطلب الآمن. لا تلصق ترويسة Authorization أو وسائط MCP أو نتائجه الخام أو محتوى المستند أو استجابة المزوّد في السجلات أو تذكرة دعم.