خادم 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 |
أي المجلدات والملفات تشغل المساحة في أحدث نسخة لحاوية أو جهاز افتراضي أو مجموعة مجلدات، وكم أضافت آخر نسخة من كل منها | قراءة |
search_files |
يبحث عن ملفات ومجلدات بالاسم في نسخ كل العناصر أو قسم واحد أو عنصر واحد (لا يبحث في الأجهزة الافتراضية)، ويسرد لكل نتيجة كل نسخة تحتويها | قراءة |
list_anomalies |
الحالات الشاذة التي لاحظها BombVault في النسخ الاحتياطية، قابلة للتصفية حسب الحالة والخطورة والقسم، مع ملخص المفتوح منها | قراءة |
get_anomaly |
إحدى هذه النتائج، مع الملاحظة المتروكة حين أُكّدت | قراءة |
start_backup |
ينسخ عنصرًا واحدًا الآن | بدء |
start_domain_backup |
ينسخ كل عنصر محمي في قسم واحد | بدء |
start_backup_everything |
يشغّل مرور «نسخ كل شيء احتياطيًا» | بدء |
cancel_backup |
يلغي نسخة عاملة بدأها هذا المفتاح | إلغاء |
يبقى هذا في واجهة الويب: الاستعادات بكل أنواعها (بما فيها تنزيل تفريغ قاعدة بيانات أو حفظه أو استيراده)، وحذف النسخ، والتقليم، وإلغاء القفل، والفحوصات والتمارين، والنسخ المتماثل خارج الموقع، والإعدادات، وبيانات الاعتماد ومفاتيح MCP، وإلغاء نسخة بدأها الجدول أو واجهة الويب أو مفتاح آخر. والأمر نفسه لتأكيد حالة شاذة أو تعليمها كمتوقعة، وهو يجري في صفحة الحالات الشاذة. السبب أن مخرجات الأدوات تحتوي أسماء ورسائل أخطاء من خادمك، ويمكن أن يحمل أي منها نصًا كُتب لتوجيه المساعد. أسوأ ما يستطيعه مساعد ينخدع بمثل هذا النص أن يبدأ نسخة ضمن الحدود أدناه أو يلغي واحدة بدأها بنفسه.
إذا كان المستودع الأساسي لعنصر بعيدًا (S3 أو REST أو SFTP أو rclone) فإن list_restore_points يتصل به، فقد يستغرق النداء وقتًا. لا يمكن سرد النسخ خارج الموقع عبر MCP. أما search_files فلا يقرأ المستودعات البعيدة، ومنها النسخ خارج الموقع، إلا حين يطلب المساعد ذلك، لأن هذا يستغرق وقتًا أطول وبعض المزوّدين يحتسبون رسومًا على البيانات التي ينزّلها. قد يستغرق البحث دقائق، لذلك يبدؤه النداء الأول في الخلفية ويستلم نداء لاحق النتيجة. ما تنظر إليه فحوصات الحالات الشاذة موصوف في الحالات الشاذة، وكيف يحتفظ عنصر ZFS بلقطة لكل مجموعة بيانات في مجموعات بيانات ZFS.
ماذا تفعل نسخة مبدوءة¶
نسخة المساعد هي النسخة نفسها التي تبدؤها واجهة الويب. تُوقف حاوية عاملة إلى أن تنتهي نسختها، مع الحاويات المضبوطة على التوقف معها. الجهاز الافتراضي بطريقة الإيقاف السليم يُطفأ ويُشغَّل من جديد. تُوقف مجموعة بيانات ZFS الحاويات المضبوطة لها بينما تؤخذ لقطتها. تستمر مجموعات المجلدات ومحرك الفلاش والإعدادات في العمل. بعد ذلك يطبّق BombVault سياسة الاحتفاظ وقد ينسخ إلى المستودع خارج الموقع. يخبر list_items المساعد بما يوقفه عنصر وكم استغرقت آخر نسخة له، وتطلب أوصاف الأدوات منه أن يخبرك قبل أن يبدأ أي شيء.
لأن النسخة توقف أشياء وتدفع نقاط استعادة قديمة إلى الخارج، فإن البدايات عبر MCP محدودة:
- 12 نسخة مبدوءة في الساعة لكل مفتاح.
- 15 دقيقة بين بدايتين عبر MCP للعنصر نفسه أو القسم أو «نسخ كل شيء احتياطيًا».
- ما لا يزيد على 4 بدايات عبر MCP للعنصر نفسه في 24 ساعة.
- حارس الاحتفاظ. حين يحتفظ قسم بعدد ثابت من نقاط الاستعادة (فقط «احتفظ بآخر N»، بلا قاعدة يومية أو أسبوعية أو شهرية، محليًا أو على وجهة خارج الموقع)، تدفع كل نسخة جديدة أقدمها إلى الخارج. يرفض BombVault حينئذ بدءًا عبر MCP لعنصر كانت أحدث N-1 نسخة ناجحة له كلها مبدوءة عبر MCP. فتبقى دائمًا نقطة استعادة واحدة على الأقل صنعها الجدول أو أنت ضمن المجموعة المحفوظة. مع «احتفظ بآخر 1» لا يستطيع مساعد نسخ ذلك العنصر إطلاقًا. تُفسح النسخة المجدولة التالية المكان من جديد. القاعدة السنوية وحدها تُعدّ «احتفظ بآخر 1»، لأنها تحتفظ بنقطة استعادة واحدة للسنة الحالية.
بدء قسم أو «نسخ كل شيء احتياطيًا» يترك العناصر التي يحجزها حد ويسمّيها في إجابته. لا واجهة الويب ولا الجدول محدودان بشيء من هذا. ميزانية الساعة تعيش في الذاكرة، فإعادة تشغيل BombVault تصفّرها.
تُحتسب البدايات عبر API ومن Home Assistant ضمن الحدود نفسها لكل عنصر مثل البدايات عبر MCP، وضمن حارس الاحتفاظ.
تفعيله¶
- افتح الإعدادات، التكاملات، خادم MCP، واضغط اختيار عميل واختر عميلك في النافذة. يجده البحث في أعلى يمينها بالاسم. العميل غير المسرود يتصل عبر عميل آخر.
- تحت المفتاح أبقِ مفتاح جديد والاسم الذي يقترحه، وهو اسم العميل، أو اكتب اسمًا يقول أين يُستخدم المفتاح، مثل «Claude Code على الحاسوب المحمول». مفتاح واحد لكل عميل يتيح لك إلغاء واحد دون المساس بالبقية. مفتاح موجود يعطي العميل مفتاحًا صنعته سابقًا.
- فعّل السماح ببدء النسخ الاحتياطي لمفتاح ينبغي أن يستطيع بدء نسخ. بدونه يقرأ المفتاح فقط. يمكنك تغيير ذلك لاحقًا في التفاصيل الخاصة بالمفتاح، ويسري التغيير على الطلب التالي للمساعد دون إعادة اتصال.
- اضغط إنشاء مفتاح. يظهر المفتاح مرة واحدة. يحتفظ 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 على ذلك الحاسوب. احفظ المفتاح أولًا في ملف نصي خاص به، في سطر واحد:
ثم نفّذ الأمر من البطاقة مرة واحدة في طرفية، مع ملء مسار ذلك الملف. خلف شهادة يثق بها حاسوبك يبدو هكذا:
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. لا تودِع أبدًا .mcp.json مكتوبًا فيه المفتاح.
Claude Desktop¶
يصل Claude Desktop إلى BombVault عبر mcp-remote، الذي يحتاج إلى Node.js على ذلك الحاسوب. احفظ المفتاح أولًا في ملف نصي خاص به، في سطر واحد، كما هو موصوف لـ Claude Code. افتح ملف التهيئة عبر Settings, Developer, Edit Config في Claude Desktop. يقع في %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. أبقِ مسار ملف المفتاح بلا مسافات: يمرّر Claude Desktop على Windows مسارًا فيه مسافة إلى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، ويجدده بنفسه.
- اضبط كلمة مرور دخول ضمن الإعدادات، الأمان. بدونها لا يقدّم BombVault أي دخول، لأنه لن يوجد من يُطلب منه الموافقة.
- اجعل BombVault متاحًا من الإنترنت عبر https بشهادة تثق بها المتصفحات، عادةً عبر وكيل عكسي. يستدعي العميل
/mcpو/oauth/و/.well-known/من خوادمه، لذا يجب أن يمرّر وكيل له تسجيل دخول خاص هذه المسارات الثلاثة إلى BombVault. تُفتح صفحة الموافقة/oauth/authorizeفي متصفحك ويمكن أن تبقى خلف دخول الوكيل. سمِّ الوكيل فيTRUSTED_PROXYأيضًا (راجع التهيئة). يحدّ BombVault تسجيلات العملاء لكل عنوان، وبدونه يبدو كل عميل قادمًا من الوكيل. - في بطاقة MCP فعّل تسجيل الدخول عبر OAuth وأدخل العنوان العام: عنوان https بدون مسار، مثل
https://backup.example.com. يرتبط كل رمز بهذا العنوان، فبعد تغييره يجب أن يسجّل كل عميل الدخول من جديد. - اختر ChatGPT أو Claude تحت اختيار عميل. تعرض النافذة رابط الموصل، وهو العنوان العام زائد
/mcp، وأين يوضع في ذلك العميل. في ChatGPT فعّل Developer mode تحت Settings, Apps & Connectors, Advanced settings، واختر Create، والصق رابط الموصل كعنوان خادم MCP واختر OAuth للمصادقة. في claude.ai افتح Settings, Connectors, Add custom connector، والصق رابط الموصل، واترك معرّف عميل OAuth وسره فارغين، واختر Connect. - يفتح العميل صفحة الموافقة. تعرض من يطلب، وإلى أين تعيدك إجابتك، ومفتاح السماح ببدء النسخ الاحتياطي الذي يبدأ معطّلًا. اختر السماح أو الرفض.
كل عميل سجّل الدخول يحصل على صف خاص به في القائمة نفسها، مع علامته. تضم التفاصيل الخاصة به سجله وإبطال والسماح ببدء النسخ الاحتياطي، وله الحدود نفسها لمفتاح. الإبطال يسري فورًا. وحين يسجّل العميل نفسه الدخول ثانية، يحل إذنه الجديد محل القديم، ويسقط إذن لم يستخدمه أحد 30 يومًا. يمكن لما يصل إلى 10 عملاء أن يكونوا مسجّلين في آن واحد، فوق 10 مفاتيح.
تقبل صفحة الموافقة طلبًا من عميل مسجّل فقط يسمّي أحد عناوين العودة المسجّلة له بدقة: https، أو عنوان loopback على أي منفذ لعميل على حاسوبك. لا يُقبل إلا تدفق رمز التفويض مع PKCE (S256)، وإجابتك مرتبطة بجلستك، فلا يستطيع موقع آخر إرسالها نيابةً عنك. تدوم رموز الوصول ساعة. يُستبدل رمز التحديث عند كل استخدام، والذي يظهر ثانية بعد ذلك يلغي الإذن، لأن شخصًا آخر يحمل نسخة. والعميل الذي يكرر آخر تحديث له خلال 30 ثانية، لأن الإجابة لم تصله، يحصل على رموز جديدة. لا يجلب BombVault وثائق بيانات العملاء الوصفية من الإنترنت، لذا يسجّل العملاء عبر التسجيل الديناميكي للعملاء.
عملاء آخرون¶
يعمل أي عميل يتحدث Streamable HTTP:
- العنوان: عنوان واجهة الويب زائد
/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 واحدة لكل طلب. تُرفض الدفعات.
- إصدارات البروتوكول 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:
- أضف العنوان في بطاقة MCP. حين تُفتح البطاقة عبر HTTPS على عنوان لا تسمّيه الشهادة، تقول ذلك وتقدم إضافة هذا العنوان إلى الشهادة. يصدر BombVault شهادته من جديد مع إضافة ذلك العنوان (يحذّر متصفحك مرة أخرى، كما فعل أول مرة). ثم اضغط تنزيل الشهادة. تضبط المقتطفات
NODE_EXTRA_CA_CERTSعلى الملف المنزَّل، فيثق العميل بهذه الشهادة بالضبط. وهذا يعني أيضًا أن كل عميل أُعدّ بتنزيل سابق يتوقف عن الاتصال بمجرد إصدار الشهادة من جديد، على هذا الحاسوب وعلى كل حاسوب آخر، إلى أن يحصل على الملف الجديد. - وكيل عكسي بشهادة موثوقة (Nginx Proxy Manager وSWAG وCaddy وTraefik). يرى العميل حينئذ شهادة الوكيل ولا يحتاج إلى شيء إضافي، ولا تحذّر البطاقة من شهادة BombVault الخاصة.
- Tailscale. يعطيك
tailscale serveأمام الحاوية، أو تكامل Tailscale في Unraid، اسمts.netبشهادة موثوقة. 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) آخر.
- لا يمكن إنشاء المفاتيح من اسم مضيف يبدو عامًا ما دامت كلمة مرور الدخول غير مضبوطة.
- كل نسخة يبدؤها مساعد، وما يسببه من تقليم وتشغيلات خارج الموقع، تُعلَّم «عبر 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 |
جاء الطلب من صفحة متصفح على مصدر (origin) آخر. استخدم عميل سطح مكتب أو سطر أوامر. |
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 أخرى كانت ستترك نقاط استعادة من صنع MCP فقط في نافذة «احتفظ بآخر N»، أو أن العنصر نال بالفعل 4 نسخ عبر MCP في آخر 24 ساعة، بما فيها الفاشلة والملغاة. في الحالة الأولى تفسح النسخة المجدولة التالية المكان، وفي الثانية يتحرر العنصر بعد 24 ساعة من أقدم تلك النسخ. وفي الحالتين يمكنك بدؤه في واجهة الويب. |
rate_limited |
استهلك المفتاح بدءاته الاثني عشر لهذه الساعة. |
not_permitted عند بدء |
المفتاح للقراءة فقط. فعّل السماح ببدء النسخ الاحتياطي في البطاقة. لا حاجة إلى إعادة اتصال. وفي إلغاء يعني أن التشغيل لم يبدأه هذا المفتاح. |
domain_off |
ذلك القسم معطّل ضمن الإعدادات، عام. |
not_found |
العنصر غير محمي بواسطة BombVault. أضفه في واجهة الويب أولًا. لا ينشئ MCP تهيئة أبدًا. |
| لا يجد العميل خادم التفويض | الدخول عبر OAuth معطّل، أو لا كلمة مرور دخول مضبوطة، أو لا يمرّر الوكيل /.well-known/ إلى BombVault. |
| تقول صفحة الموافقة إن عنوان العودة غير مسجّل | أرسل العميل عنوان عودة لم يسجّله. أزل الموصل في العميل وأضفه من جديد. |
عميل مسجّل الدخول يحصل على 401 |
أُلغي إذنه، أو انتهت صلاحيته بعد 30 يومًا دون استخدام، أو تغيّر العنوان العام. يسجّل العميل الدخول من جديد. |
لا تضبط متغير البيئة MCPGODEBUG على الحاوية. فهو يغيّر سلوك مكتبة MCP، والقيمة المشوّهة توقف BombVault عند البدء قبل أن يكتب سطر سجل واحدًا.