انتقل إلى المحتوى

خادم MCP

يحتوي BombVault على خادم مدمج لبروتوكول Model Context Protocol (MCP)، وهو البروتوكول الذي يصل به مساعدو الذكاء الاصطناعي مثل Claude Code وClaude Desktop إلى أدوات خارجية. عبره يستطيع المساعد قراءة حال نسخك الاحتياطية، وإن سمحت له، بدء نسخة احتياطية أو إلغاء نسخة بدأها بنفسه. يبقى متوقفًا حتى تنشئ مفتاحًا أو تفعّل تسجيل الدخول عبر OAuth: وحتى ذلك الحين تجيب نقطة النهاية /mcp على كل شيء بـ 404.

ما يستطيعه المساعد وما لا يستطيعه

الأداة ما تفعله النوع
get_health الإصدار واسم النسخة المثبتة وهل هناك نسخ احتياطي جارٍ وما المسموح لهذا المفتاح قراءة
get_status حالة الحماية لكل نطاق: آخر نسخة ناجحة، والفاصل المتوقع، والتحققات وفحوص النسخ الخارجي، والتشغيلات المجدولة التالية، والنسخ المنتظرة حتى يهدأ التطبيق، ولنطاق الحاويات أحدث اختبار تشغيل قراءة
get_coverage ما يحميه BombVault وما لا يحميه، مع السبب لكل عنصر قراءة
list_items كل حاوية وآلة افتراضية ومجموعة مجلدات محمية، وذاكرة الفلاش وإعدادات التطبيق، مع الجدولة وما يوقفه النسخ الاحتياطي وآخر نسخة ومدتها؛ وتعرض حاويات قواعد البيانات آخر تفريغ لها أيضًا، وتظهر أيضًا مجموعات بيانات ZFS مع نتيجة آخر فحص لها؛ ويحمل كل عنصر آخر فحص استعادة له، وتحمل الحاوية آخر اختبار تشغيل لها أو سبب تعذّر اختبارها؛ الحاوية التي أُعيد إنشاؤها بإعدادات أخرى منذ آخر نسخة تسرد ما تغيّر قراءة
list_runs سجل التشغيلات، الأحدث أولًا، مع ترشيح حسب النطاق والعنصر والحالة والنوع والوقت؛ النسخة البطيئة التي عطّلها شيء واحد تذكره قراءة
list_restore_points نقاط الاستعادة لعنصر واحد من مستودعه الأساسي، ولحاوية أيضًا تفريغات قواعد بياناتها، ولمجموعة بيانات ZFS نقطة استعادة واحدة لكل نسخة، مع لقطة لكل مجموعة بيانات تحتها قراءة
get_activity ما يعمل الآن، مع المرحلة والنسبة المئوية قراءة
get_storage_stats سجل حجم المستودع الأساسي لنطاق ما ونموه الأسبوعي، والمساحة المستخدمة والحرة والإجمالية على القرص أو الوجهة البعيدة لكل مستودع من مستودعاته قراءة
get_size_breakdown المجلدات والملفات التي تشغل المساحة في أحدث نسخة احتياطية لحاوية أو آلة افتراضية أو مجموعة مجلدات، وكم منها أضافته آخر نسخة قراءة
list_anomalies الحالات الشاذة التي لاحظها BombVault في النسخ الاحتياطية، مع إمكانية التصفية حسب الحالة والخطورة والنطاق، وملخص لما هو مفتوح قراءة
get_anomaly إحدى هذه الحالات، مع التعليق الذي تُرك عند الإقرار بها قراءة
start_backup ينسخ عنصرًا واحدًا فورًا بدء
start_domain_backup ينسخ كل عنصر محمي في نطاق واحد بدء
start_backup_everything يشغّل جولة النسخ الاحتياطي الشامل بدء
cancel_backup يلغي نسخًا احتياطيًا جاريًا بدأه هذا المفتاح إلغاء

يبقى ما يلي في واجهة الويب: الاستعادة بكل أنواعها (بما في ذلك تنزيل تفريغ قاعدة بيانات أو حفظه أو استيراده)، وحذف النسخ، وprune وunlock، والفحوص والتدريبات، والنسخ المتماثل الخارجي، والإعدادات، وبيانات الاعتماد ومفاتيح MCP، وإلغاء نسخ احتياطي بدأه الجدول أو واجهة الويب أو مفتاح آخر. وينطبق الأمر نفسه على الإقرار بحالة شاذة أو وسمها بأنها متوقعة، ويتم ذلك في صفحة الحالات الشاذة. السبب أن ردود الأدوات تحوي أسماء ورسائل خطأ من خادمك، وقد يحمل أيٌّ منها نصًا كُتب لتوجيه المساعد. والمساعد الذي ينخدع بمثل هذا النص لا يستطيع في أسوأ الأحوال إلا أن يبدأ نسخًا احتياطيًا ضمن الحدود المذكورة أدناه، أو أن يلغي نسخًا بدأه هو.

إذا كان المستودع الأساسي لعنصر ما في مكان آخر (S3 أو REST أو SFTP أو rclone)، فإن list_restore_points يتصل به، وقد يستغرق الاستدعاء بعض الوقت. لا يمكن عرض النسخ الخارجية عبر MCP. تجد ما تفحصه اختبارات الحالات الشاذة في الميزات، وكيف يحتفظ عنصر ZFS بلقطة لكل مجموعة بيانات في مجموعات بيانات ZFS.

ماذا يفعل النسخ الاحتياطي عند بدئه

النسخ الاحتياطي الذي يبدؤه المساعد هو نفسه الذي تبدؤه واجهة الويب. تتوقف الحاوية العاملة حتى تنتهي نسختها، ومعها الحاويات المضبوطة على التوقف معها. وتُطفأ الآلة الافتراضية ذات الطريقة "graceful" ثم تُشغّل من جديد. وتوقف مجموعة بيانات ZFS الحاويات المضبوطة لها طوال التقاط لقطتها. أما مجموعات المجلدات وذاكرة الفلاش والإعدادات فتواصل العمل. بعد ذلك يطبق BombVault سياسة الاحتفاظ وقد ينسخ إلى المستودع الخارجي. تخبر list_items المساعد بما يوقفه العنصر وبمدة آخر نسخة له، وتطلب منه أوصاف الأدوات أن يخبرك بذلك قبل أن يبدأ أي شيء.

لأن النسخ الاحتياطي يوقف الخدمات ويدفع نقاط الاستعادة القديمة إلى الخارج، فإن البدء عبر MCP محدود:

  • 12 نسخة احتياطية مبدوءة في الساعة لكل مفتاح.
  • 15 دقيقة بين بدأين عبر MCP للعنصر نفسه أو النطاق نفسه أو النسخ الاحتياطي الشامل.
  • 4 بدايات عبر MCP للعنصر نفسه على الأكثر خلال 24 ساعة.
  • حارس الاحتفاظ. حين يحتفظ نطاق بعدد ثابت من نقاط الاستعادة (فقط "احتفظ بآخر N"، دون قاعدة يومية أو أسبوعية أو شهرية، محليًا أو على وجهة خارجية)، تدفع كل نسخة جديدة الأقدم إلى الخارج. عندئذ يرفض BombVault بدء عنصر عبر MCP إذا كانت أحدث N-1 نسخة ناجحة له قد بُدئت كلها عبر MCP. وبهذا تبقى في المجموعة المحتفظ بها دائمًا نقطة استعادة واحدة على الأقل صنعها الجدول أو صنعتها أنت. ومع "احتفظ بآخر 1" لا يستطيع المساعد نسخ ذلك العنصر إطلاقًا. والنسخة المجدولة التالية تفسح المجال من جديد. قاعدة سنوية وحدها تُحسب مثل "احتفظ بآخر 1"، لأنها تحتفظ بنقطة استعادة واحدة فقط للسنة الجارية.

عند بدء نطاق أو النسخ الاحتياطي الشامل تُترك العناصر التي يحجزها أحد الحدود، وتُذكر أسماؤها في الرد. لا يمس أيٌّ من هذه الحدود واجهة الويب أو الجدول. وحصة الساعة محفوظة في الذاكرة، لذا تعيدها إعادة تشغيل BombVault إلى الصفر.

تُحسب عمليات البدء عبر واجهة API ومن Home Assistant ضمن حدود العنصر نفسها مع عمليات البدء عبر MCP، وضمن حماية الاحتفاظ.

التفعيل

  1. افتح الإعدادات، التكاملات، خادم MCP وانقر زر العميل الذي تستخدمه. العميل غير الموجود في القائمة يتصل عبر عميل آخر.
  2. تحت المفتاح أبقِ مفتاح جديد والاسم المقترح، وهو اسم العميل، أو اكتب اسما يدل على مكان استخدام المفتاح، مثل "Claude Code على الحاسوب المحمول". مفتاح واحد لكل عميل يتيح لك إلغاء واحد دون المساس بالبقية. مفتاح موجود يعطي العميل مفتاحا أنشأته من قبل.
  3. شغّل السماح ببدء النسخ الاحتياطي لمفتاح يجب أن يستطيع بدء النسخ؛ من دونه يقرأ المفتاح فقط. يمكنك تغيير ذلك لاحقا على بطاقة المفتاح، ويسري التغيير من الطلب التالي للمساعد دون إعادة اتصال.
  4. انقر إنشاء مفتاح. يُعرض المفتاح مرة واحدة. لا يحتفظ BombVault إلا ببصمته ولا يمكنه عرضه مرة أخرى، فانسخه الآن. إذا أغلقت النافذة قبل أن يستخدم العميل المفتاح، تبقى البطاقة تعرضه حتى تؤكد أنك نسخته.

من دون كلمة مرور لتسجيل الدخول تكون واجهة الويب نفسها مفتوحة لكل من في شبكتك، ومن يستطيع فتحها يستطيع أيضًا إنشاء مفتاح. البطاقة تقول ذلك. وإذا فتحت BombVault باسم يبدو عامًا (مثل bombvault.example.com خلف وكيل عكسي) ولم تكن هناك كلمة مرور لتسجيل الدخول، فلا يمكن إنشاء مفاتيح أو استبدالها من ذلك العنوان، حتى لا تستطيع أي صفحة على الإنترنت دفع متصفحك إلى إنشاء مفتاح. عيّن كلمة مرور لتسجيل الدخول، أو افتح BombVault بعنوان IP الخاص به أو باسم محلي مثل tower أو tower.local.

مفاتيحك وسجلها

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

بجانب الاسم تعرض البطاقة شعار العميل الذي أُنشئ المفتاح له. المفتاح الذي أُنشئ عبر عميل آخر، أو قبل أن تسرد البطاقة العملاء، يعرض مفتاحا بدلا من ذلك.

يفتح السجل في البطاقة ما فعله ذلك المفتاح. تأتي أولًا النسخ الاحتياطية التي بدأها، كل منها بحالتها ورابط إلى ذلك التشغيل في سجل النشاط على لوحة المعلومات. وتحتها استدعاءاته، الأحدث أولًا، مع الأداة وما آل إليه الاستدعاء. يذكر الرفض سببه: المفتاح للقراءة فقط، أو أن حارس الاحتفاظ أوقف النسخ، أو أن نسخًا احتياطيًا آخر كان يعمل، أو أن العنصر نُسخ من خارج واجهة الويب قبل دقائق، أو أن المفتاح أرسل طلبات كثيرة جدًا. ويرتبط الإلغاء بالتشغيل الذي يخصه.

يحتفظ BombVault بإدخالات كل مفتاح لمدة تصل إلى 30 يومًا: أحدث 500 عملية بدء وإلغاء ناجحة، وإلى جانبها أحدث 200 استدعاء آخر (قراءات ورفض وأخطاء)، فلا يستطيع مساعد يستعلم مرارًا عن نسخ احتياطي جارٍ أو يعيد محاولة استدعاء مرفوض أن يُخرج بدء ذلك النسخ من السجل. يخزّن لكل استدعاء الأداة والنتيجة والتشغيل الذي ذكره الإلغاء. لا يخزّن أبدًا ما أرسله المساعد، ولا المفتاح ولا بصمته. حزمة التشخيص تعدّ الإدخالات فقط، وتصدير الإعدادات يستبعدها.

ربط عميل

لكل عميل زر في البطاقة، تحت على هذا الحاسوب أو في السحابة. يفتح الزر نافذة من ثلاث خطوات: المفتاح؛ والإعدادات لذلك العميل مع العنوان الذي فتحت به البطاقة وزر للنسخ ومكان وجود الإعدادات، ومع شهادة BombVault الخاصة ما يحتاجه العميل ليثق بها؛ ثم انتظار أول استدعاء من العميل. تراقب النافذة آخر استخدام للمفتاح وتصبح خضراء حين يصل ذلك الاستدعاء.

تُبقي النافذة المفتاح بعيدا عن أي سطر أوامر. حين يستطيع العميل قراءته من متغير بيئة (BOMBVAULT_MCP_KEY) أو من طلب مخفي أو من ملف خاص به، تكتفي الإعدادات بذكر اسمه. وحين لا تتوفر للعميل طريقة كهذه، يوضع المفتاح في ملف إعداداته أو في إعداداته، وتقول النافذة ذلك. وحين لا تذكر وثائق العميل كيف يتعامل مع شهادة لا يعرفها، تكتب النافذة تلك الخطوة على أنها ما تفعله إذا رفض العميل شهادة BombVault.

العميل الإعداد مصدر المفتاح
AnythingLLM ملف الإعدادات ملف الإعدادات
Antigravity ملف الإعدادات متغير بيئة
Claude Code أمر ملف المفتاح
Claude Desktop ملف الإعدادات ملف المفتاح
Cline ملف الإعدادات ملف الإعدادات
Codex CLI ملف الإعدادات متغير بيئة
Continue ملف الإعدادات ~/.continue/.env
Copilot CLI ملف الإعدادات ملف الإعدادات
Cursor ملف الإعدادات متغير بيئة
Gemini CLI ملف الإعدادات متغير بيئة
GitHub Copilot (VS Code) ملف الإعدادات طلب مخفي
Goose ملف الإعدادات متغير بيئة
Jan نموذج في التطبيق إعدادات التطبيق
JetBrains (AI Assistant, Junie) ملف الإعدادات ملف الإعدادات
Kimi Code ملف الإعدادات ملف الإعدادات
LM Studio ملف الإعدادات ملف الإعدادات
Mistral Vibe ملف الإعدادات متغير بيئة
Msty نموذج في التطبيق إعدادات التطبيق
n8n نموذج في التطبيق بيانات اعتماد n8n
Open WebUI نموذج في التطبيق إعدادات التطبيق
opencode ملف الإعدادات متغير بيئة
Perplexity (Mac) نموذج في التطبيق ملف المفتاح
Qwen Code ملف الإعدادات متغير بيئة
Roo Code ملف الإعدادات متغير بيئة
Visual Studio ملف الإعدادات ملف الإعدادات
Warp ملف الإعدادات ملف الإعدادات
Windsurf ملف الإعدادات متغير بيئة
Zed ملف الإعدادات ملف الإعدادات
Grok نموذج، في السحابة خوادم المزود
Le Chat نموذج، في السحابة خوادم المزود
ChatGPT تسجيل الدخول عبر OAuth، في السحابة رمز وصول، انظر أدناه
Claude (claude.ai) تسجيل الدخول عبر OAuth، في السحابة رمز وصول، انظر أدناه

تشرح الأقسام التالية إعداد Claude Code وClaude Desktop بتفصيل أكبر، وتذكر ما يحتاجه أي عميل آخر.

Claude Code

يصل Claude Code إلى BombVault عبر mcp-remote الذي يحتاج إلى Node.js على ذلك الحاسوب. احفظ المفتاح أولًا في ملف نصي خاص به، في سطر واحد:

X-API-Key: <your key>

ثم شغّل أمر البطاقة مرة واحدة في طرفية بعد أن تضع فيه مسار ذلك الملف. خلف شهادة يثق بها حاسوبك يبدو هكذا:

claude mcp add bombvault --scope user -- npx -y mcp-remote@latest https://bombvault.example.com/mcp --header-file "<path of the file with your key>"

مع شهادة BombVault الخاصة (انظر TLS والشهادات) يوجّه الأمر أيضًا Node.js إلى الشهادة التي نزّلتها:

claude mcp add bombvault --scope user -e "NODE_EXTRA_CA_CERTS=<path of the downloaded bombvault-cert.pem>" -- npx -y mcp-remote@latest https://192.168.1.10:3443/mcp --header-file "<path of the file with your key>"

تحقق من الاتصال بالأمر /mcp داخل Claude Code. يجعل --scope user خادم BombVault متاحًا في كل مشاريعك. لا يحفظ Claude Code إلا مسار ملف المفتاح، فلا يظهر المفتاح في الأمر ولا في سجل الصدفة، ولا في قائمة العمليات. احفظ الملف حيث لا يستطيع أحد غيرك قراءته، وخارج أي مجلد تعمل له commit. يجعل @latest الأداة npx تجلب نسخة حديثة من mcp-remote؛ وبدونه تُستخدم نسخة أقدم مثبتة على مستوى النظام، وهي لا تدعم --header-file.

لا تكتب ${BOMBVAULT_MCP_KEY} في وسائط mcp-remote الخاصة بـ Claude Code. يستبدل Claude Code مثل هذا المرجع بقيمته من بيئته قبل أن يشغّل mcp-remote، فيصل المفتاح إلى سطر أوامر تلك العملية، حيث تستطيع برامج أخرى ومستخدمون آخرون على الحاسوب قراءته.

من دون Node.js، وخلف شهادة يثق بها حاسوبك فقط، يستطيع Claude Code الاتصال بنفسه. ضع ملف .mcp.json في مجلد المشروع:

{
  "mcpServers": {
    "bombvault": {
      "type": "http",
      "url": "https://bombvault.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${BOMBVAULT_MCP_KEY}"
      }
    }
  }
}

عيّن BOMBVAULT_MCP_KEY حيث يبدأ Claude Code، مثلًا تحت "env" في ~/.claude/settings.json أو في ملف تعريف الصدفة، عبر محرر نصوص لا بكتابته في سطر الأوامر. هنا يكون المرجع آمنًا، لأن Claude Code لا يشغّل عملية ثانية يصل إليها المفتاح. ولا تعمل شهادة BombVault الخاصة بهذه الطريقة: فالاتصال الذي يجريه Claude Code بنفسه يرفضها حتى مع تعيين NODE_EXTRA_CA_CERTS. لا تقم أبدًا بعمل commit لملف .mcp.json مكتوب فيه المفتاح.

Claude Desktop

يصل Claude Desktop إلى BombVault عبر mcp-remote الذي يحتاج إلى Node.js على ذلك الحاسوب. احفظ المفتاح أولا في ملف نصي خاص به، في سطر واحد، كما هو موضح لـ Claude Code. افتح ملف الإعدادات في Claude Desktop من Settings, Developer, Edit Config. يوجد في %APPDATA%\Claude\claude_desktop_config.json على Windows وفي ~/Library/Application Support/Claude/claude_desktop_config.json على macOS. أضف مدخل البطاقة داخل "mcpServers" بجانب الخوادم الموجودة فيه، ثم أعد تشغيل Claude Desktop:

{
  "mcpServers": {
    "bombvault": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://192.168.1.10:3443/mcp", "--header-file", "<path of the file with your key>"],
      "env": {
        "NODE_EXTRA_CA_CERTS": "<path of the downloaded bombvault-cert.pem>"
      }
    }
  }
}
  • NODE_EXTRA_CA_CERTS موجود فقط لشهادة BombVault الخاصة. احذفه خلف شهادة يثق بها حاسوبك أصلًا.
  • يضاف --allow-http فقط لعنوان http:// عادي.
  • على Windows اكتب المسارات بشرطات مائلة للأمام، مثل C:/Users/sam/bombvault-key.txt، لأن الشرطة المائلة العكسية المفردة ليست JSON صالحا. اجعل مسار ملف المفتاح خاليا من المسافات: على Windows يمرر Claude Desktop المسار الذي فيه مسافة إلى npx على جزأين.
  • لا تذكر الإعدادات إلا ملف المفتاح، فلا يظهر المفتاح فيها ولا في قائمة العمليات. احفظ الملف حيث لا يستطيع أحد غيرك قراءته.

العملاء في السحابة

يستدعي ChatGPT وClaude على claude.ai وGrok وLe Chat خدمة BombVault من خوادم مزوديها، لذا يجب أن يكون BombVault متاحًا من الإنترنت بشهادة موثوقة علنًا، خلف وكيل عكسي مثلًا؛ ويرفض Le Chat الشهادات الموقعة ذاتيًا. يمكن لتسجيل دخول على الوكيل أن يحمي واجهة الويب، لكن يجب أن يصل /mcp إلى BombVault من دونه: فهذه الخدمات لا تستطيع تسجيل الدخول إلى وكيل، وBombVault يتحقق بنفسه من مفتاحها أو رمزها. يرسل Grok وLe Chat مفتاحًا ثابتًا، وأزرارهما تضبطهما مثل البقية. أما ChatGPT، وClaude على claude.ai في معظم المؤسسات، فلا يتصلان إلا عبر تسجيل الدخول بـ OAuth، الموصوف أدناه.

تسجيل الدخول عبر OAuth

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

  1. اضبط كلمة مرور للدخول ضمن الإعدادات، الأمان. من دونها لا يعرض BombVault أي تسجيل دخول، إذ لن يكون هناك من يُطلب منه الموافقة.
  2. اجعل BombVault متاحًا من الإنترنت عبر https بشهادة تثق بها المتصفحات، عادةً عبر وكيل عكسي. يستدعي العميل /mcp و/oauth/ و/.well-known/ من خوادمه، لذا يجب على الوكيل الذي له تسجيل دخول خاص أن يمرّر هذه المسارات الثلاثة إلى BombVault. تُفتح صفحة الموافقة على /oauth/authorize في متصفحك أنت، ويمكن أن تبقى خلف تسجيل دخول الوكيل. اذكر الوكيل أيضًا في TRUSTED_PROXY (انظر الإعدادات). يحدّ BombVault من تسجيلات العملاء لكل عنوان، وبدون ذلك يبدو كل عميل كأنه قادم من الوكيل.
  3. في بطاقة MCP فعّل تسجيل الدخول عبر OAuth وأدخل العنوان العام: عنوان https من دون مسار، مثل https://backup.example.com. كل رمز مرتبط بهذا العنوان، لذا بعد أي تغيير يجب على كل عميل تسجيل الدخول من جديد.
  4. انقر زر ChatGPT أو Claude. يعرض مربع الحوار رابط الموصل، أي العنوان العام متبوعًا بـ /mcp، ومكان إدخاله في ذلك العميل. في ChatGPT فعّل وضع المطوّر ضمن الإعدادات، التطبيقات والموصلات، الإعدادات المتقدمة، واختر إنشاء، والصق رابط الموصل بوصفه رابط خادم MCP، واختر OAuth للمصادقة. في claude.ai افتح الإعدادات، الموصلات، إضافة موصل مخصص، والصق رابط الموصل، واترك معرّف عميل OAuth والسر فارغين، واختر اتصال.
  5. يفتح العميل صفحة الموافقة. تعرض الصفحة من يطلب، وإلى أين تعيدك إجابتك، ومفتاح السماح ببدء النسخ الاحتياطي الذي يبدأ مطفأً. اختر السماح أو الرفض.

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

لا تقبل صفحة الموافقة طلبًا إلا من عميل مسجّل يذكر بالضبط أحد عناوين الرجوع التي سجّلها: https، أو عنوان loopback على أي منفذ لعميل على حاسوبك أنت. لا يُقبل إلا تدفق رمز التفويض مع PKCE (S256)، وإجابتك مرتبطة بجلستك، فلا يستطيع أي موقع آخر إرسالها نيابةً عنك. تصلح رموز الوصول لمدة ساعة. يُستبدل رمز التحديث عند كل استخدام، وإن ظهر أحدها مرة أخرى بعد ذلك يبطل BombVault الإذن، لأن شخصًا آخر يملك نسخة منه. أما العميل الذي يكرر آخر تحديث له خلال 30 ثانية لأن الرد لم يصله، فيحصل بدلًا من ذلك على رموز جديدة. لا ينزّل BombVault بيانات وصفية للعملاء من الإنترنت، لذا يسجّل العملاء أنفسهم عبر التسجيل الديناميكي للعملاء.

عملاء آخرون

يصلح أي عميل يتحدث Streamable HTTP:

  • العنوان URL: عنوان واجهة الويب مضافًا إليه /mcp، مثل https://192.168.1.10:3443/mcp.
  • المفتاح في Authorization: Bearer <key> أو في X-API-Key: <key>. إن أُرسل الاثنان فيجب أن يحملا المفتاح نفسه.
  • POST مع Content-Type: application/json وAccept: application/json, text/event-stream.
  • رسالة JSON-RPC واحدة لكل طلب؛ تُرفض الدفعات (batch).
  • إصدارات البروتوكول 2026-07-28 و2025-11-25 و2025-06-18 و2025-03-26.

TLS والشهادات

يقدم BombVault بروتوكول HTTPS بشهادة أصدرها بنفسه، وفي البداية لا تذكر هذه الشهادة إلا localhost و127.0.0.1 و::1. يرفضها Claude Code وmcp-remote على عنوان في الشبكة المحلية. هذه طرق الالتفاف على ذلك، بالترتيب الذي يناسب معظم تثبيتات Unraid:

  1. أضف العنوان في بطاقة MCP. حين تفتح البطاقة عبر HTTPS على عنوان لا تذكره الشهادة، تقول البطاقة ذلك وتعرض أضف هذا العنوان إلى الشهادة. عندئذ يعيد BombVault إصدار شهادته مع ذلك العنوان (ويحذرك المتصفح مرة أخرى كما في المرة الأولى). ثم انقر تنزيل الشهادة؛ تضبط المقتطفات NODE_EXTRA_CA_CERTS على الملف الذي نزّلته، فيثق العميل بتلك الشهادة تحديدًا. ويعني هذا أيضًا أن كل عميل أُعدّ بملف نُزّل من قبل يتوقف عن الاتصال بمجرد إعادة إصدار الشهادة، على هذا الحاسوب وعلى أي حاسوب آخر، إلى أن يحصل على الملف الجديد.
  2. وكيل عكسي بشهادة موثوقة (Nginx Proxy Manager أو SWAG أو Caddy أو Traefik). يرى العميل عندئذ شهادة الوكيل ولا يحتاج إلى شيء آخر، ولا تحذر البطاقة من شهادة BombVault الخاصة.
  3. Tailscale. يمنحك tailscale serve أمام الحاوية، أو تكامل Tailscale في Unraid، اسمًا من ts.net بشهادة موثوقة.
  4. HTTP_ONLY=true، فقط خلف وكيل ينهي TLS أو في شبكة تثق بها تمامًا. يحوّل واجهة الويب كلها إلى HTTP عادي، ويتطلب تعديل إعدادات الحاوية، ويرسل المفتاح دون تشفير.

لا تعيّن أبدًا NODE_TLS_REJECT_UNAUTHORIZED=0. فهذا يوقف فحص الشهادات لكل ما تتحدث إليه عملية Node.js تلك.

يجب على الوكيل العكسي أن يمرر ترويسة Authorization (أو X-API-Key)، وهذا ما تفعله الوكلاء ما لم يُطلب منها غير ذلك، ويجب ألا يخزّن /mcp مؤقتًا أو يعيد كتابته. هذه كتلة location لـ Nginx أو Nginx Proxy Manager تتحقق أيضًا من شهادة BombVault:

location /mcp {
    proxy_pass https://192.168.1.10:3443;
    proxy_ssl_verify on;
    proxy_ssl_trusted_certificate /data/bombvault-cert.pem;
    proxy_ssl_name localhost;
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_set_header Host $host;
}

خلف وكيل يحمل كل طلب عنوان الوكيل. عندئذ تحجب خمسة مفاتيح خاطئة من عميل واحد سيئ الإعداد جميع عملاء MCP خلف ذلك الوكيل لمدة دقيقة. اذكر الوكيل في TRUSTED_PROXY (انظر الإعدادات) ليكون العدّ لكل عميل على حدة.

نموذج الأمان

  • من دون مفتاح نشط ومع إيقاف تسجيل الدخول عبر OAuth يجيب /mcp بـ 404.
  • لا يُعرض تسجيل الدخول عبر OAuth إلا ما دامت كلمة مرور الدخول مضبوطة. تُخزَّن الرموز والأكواد وأسرار العملاء كبصمات فقط، ولا يصلح الرمز إلا للعنوان الذي أُصدر له.
  • يستطيع العميل التسجيل 10 مرات على الأكثر في الساعة من عنوان واحد، ويحتفظ BombVault بـ 100 عميل مسجّل على الأكثر لم يسجّل أحد الدخول بهم، كلًّا منهم ليوم واحد. تُحتسب الأكواد ورموز التحديث الخاطئة ضمن الحظر نفسه المطبق على المفاتيح الخاطئة.
  • تتصرف الأذونات مثل المفاتيح عند استعادة نسخة احتياطية للإعدادات أو تغيّر APP_KEY: بعد الاستعادة يجب على كل عميل تسجيل الدخول من جديد.
  • لا استثناء لأي عنوان. الطلبات من localhost أو من مضيف Unraid أو من وكيل عكسي أو من tailscale serve تحتاج إلى مفتاح كغيرها، حتى حين لا تكون لواجهة الويب كلمة مرور لتسجيل الدخول.
  • لا تُحفظ المفاتيح إلا كبصمات، وتُعرض مرة واحدة، ويمكن إعادة تسميتها واستبدالها وإبطالها. حتى 10 مفاتيح نشطة، لكل منها مفتاح تبديل خاص السماح ببدء النسخ الاحتياطي.
  • كل إنشاء واستبدال وتغيير في الصلاحية وإبطال يرسل إشعارًا عبر قنوات الإشعارات لديك مع العنوان الذي جاء منه، ما لم تكن الإشعارات متوقفة.
  • 5 مفاتيح خاطئة في الدقيقة لكل عنوان، ثم 429. و120 طلبًا في الدقيقة و12 نسخة احتياطية مبدوءة في الساعة لكل مفتاح، إضافة إلى مهلة الانتظار وحارس الاحتفاظ المذكورين أعلاه.
  • تُرفض الطلبات القادمة من صفحة متصفح ذات أصل (origin) مختلف.
  • ما دامت كلمة مرور تسجيل الدخول غير معيّنة، لا يمكن إنشاء مفاتيح من اسم مضيف يبدو عامًا.
  • كل نسخة احتياطية يبدؤها مساعد، وتشغيلات prune والنسخ الخارجي الناتجة عنها، تُعلَّم بعبارة "عبر MCP" مع اسم المفتاح في سجل النشاط وفي لوحة الأخطاء وفي إشعار النسخ الاحتياطي.
  • يُكتب كل استدعاء لأداة في سجل الحاوية مع معرّف المفتاح وآخر أربعة أحرف منه (ولا يُكتب اسمه أبدًا) ويُحسب في /metrics (bombvault_mcp_requests_total وbombvault_mcp_tool_calls_total وbombvault_mcp_active_keys).
  • استعادة نسخة احتياطية من الإعدادات تبطل جميع المفاتيح، لأن قاعدة البيانات المستعادة قد تحتوي على مفاتيح أبطلتها بعد حفظها. أنشئ مفاتيح جديدة بعد ذلك.
  • يتوقف المفتاح عن العمل حين يتغير APP_KEY (إعادة تثبيت أو استعادة إلى حاوية أخرى). تكتشف البطاقة ذلك وتعلّم المفتاح، ويمنحه استبدال المفتاح سرًا صالحًا من جديد.
  • عامل المفتاح كأنه كلمة مرور. العميل الذي لا يستطيع قراءة المفتاح من متغير بيئة أو من طلب أو من ملف مفتاح يحفظه نصا عاديا في إعداداته، وتقول نافذته ذلك. على حاسوب تثق به أقل، استخدم مفتاحا للقراءة فقط.

ما الذي يغادر الجهاز

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

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

ما تراه ما يعنيه
404 لا يوجد مفتاح نشط وتسجيل الدخول عبر OAuth متوقف، أو المسار خاطئ مثل /api/mcp. نقطة النهاية هي /mcp.
401 المفتاح مفقود أو مكتوب خطأً أو أُبطل أو استُبدل. ربما يسقط وكيلٌ ترويسة Authorization (جرّب X-API-Key). إذا علّمت البطاقة المفتاح بأنه لم يعد صالحًا فقد تغير APP_KEY: استبدل المفتاح.
403 جاء الطلب من صفحة متصفح ذات أصل مختلف. استخدم عميلًا لسطح المكتب أو لسطر الأوامر.
405 مع GET أمر طبيعي. نقطة الاتصال لا تقبل إلا POST.
400 "Accept must contain both 'application/json' and 'text/event-stream'" العميل أقدم من أن يدعم Streamable HTTP. حدّثه.
400 "batch requests are not accepted" يرسل العميل دفعات JSON-RPC. أرسل رسالة واحدة لكل طلب.
429 مفاتيح خاطئة كثيرة من هذا العنوان، أو أكثر من 120 طلبًا في الدقيقة بمفتاح واحد. انتظر دقيقة وتحقق مما إذا كان المساعد عالقًا في حلقة.
أخطاء فيها "certificate" أو "self-signed" أو "unable to verify" لا يثق العميل بشهادة BombVault. انظر TLS والشهادات.
busy نسخ احتياطي آخر أو مهمة صيانة يشغل ذلك النطاق. أعد المحاولة حين تنتهي.
cooldown بُدئ هذا العنصر أو هذا النطاق أو النسخ الاحتياطي الشامل من خارج واجهة الويب قبل أقل من 15 دقيقة.
retention_guard نسخة MCP أخرى كانت ستترك في نافذة "احتفظ بآخر N" نقاط استعادة من MCP فقط، أو أن العنصر حصل بالفعل على 4 نسخ عبر MCP خلال آخر 24 ساعة، بما فيها النسخ الفاشلة والملغاة. في الحالة الأولى تفسح النسخة المجدولة التالية المجال، وفي الثانية يصبح العنصر متاحًا من جديد بعد 24 ساعة من أقدم تلك النسخ. ويمكنك دائمًا أن تبدأها من واجهة الويب.
rate_limited استهلك المفتاح بداياته الاثنتي عشرة لهذه الساعة.
not_permitted عند البدء المفتاح للقراءة فقط. فعّل السماح ببدء النسخ الاحتياطي في البطاقة؛ لا حاجة إلى إعادة الاتصال. وعند الإلغاء يعني أن هذا المفتاح لم يبدأ التشغيل.
domain_off هذا النوع من النسخ الاحتياطي متوقف في الإعدادات.
not_found لا يحمي BombVault هذا العنصر. أضفه أولًا في واجهة الويب؛ فـ MCP لا ينشئ إعدادات أبدًا.
لا يجد العميل خادم التفويض تسجيل الدخول عبر OAuth متوقف، أو لا توجد كلمة مرور للدخول، أو لا يمرّر الوكيل /.well-known/ إلى BombVault.
تقول صفحة الموافقة إن عنوان الرجوع غير مسجّل أرسل العميل عنوان رجوع لم يسجّله. أزل الموصل في العميل ثم أضفه من جديد.
يتلقى عميل مسجّل الدخول 401 أُبطل إذنه، أو انتهت صلاحيته بعد 30 يومًا دون استخدام، أو تغيّر العنوان العام. سيسجّل العميل الدخول من جديد.

لا تعيّن متغير البيئة MCPGODEBUG على الحاوية. فهو يغيّر سلوك مكتبة MCP، والقيمة غير الصالحة توقف BombVault عند البدء قبل أن يكتب سطرًا واحدًا في السجل.