تخطَّ إلى المحتوى

ربط Gemini CLI بخادم MCP للنصوص الإسلامية

أضف خادم MCP لمعرض القرآن إلى Gemini CLI بأمر واحد أو عبر settings.json: كتب عربية تراثية وتوثيق الصفحة المطبوعة، دون مفتاح.

في هذه الصفحة

بلا حساب ولا تسجيل دخول ولا مفتاح. أمر واحد:

gemini mcp add --transport http quran-gallery https://qurangallery.com/mcp/shamela

الخطوات

  1. شغّل الأمر أعلاه داخل مجلد مشروعك. يكتب الخادم في .gemini/settings.json داخل ذلك المجلد. أضف --scope user ليكتبه في ~/.gemini/settings.json فيعمل في كل مشروع.

  2. شغّل gemini mcp list. ينبغي أن يظهر quran-gallery بالحالة Connected.

    طرفية: الأمر gemini mcp add يكتب الخادم في .gemini/settings.json، والأمر gemini mcp list يعرض quran-gallery بالحالة Connected.

  3. شغّل gemini واسأل سؤالًا يحتاج إلى نص (أدناه). يسألك Gemini CLI قبل كل استدعاء أداة أول مرة. وافق عليه.

تذكر الإجابة الطبعة والمجلد والصفحة المطبوعة، ورابطًا إلى الصفحة في قارئ المكتبة. شكل الرابط https://qurangallery.com/maktabah/book/{bookId}/{pageId}، مثل qurangallery.com/maktabah/book/1681/10 لصحيح البخاري، فيفتح الصفحة على Quran Gallery:

طرفية: gemini يجيب بصحيح البخاري، الطبعة السلطانية، المجلد 1 الصفحة 6، مع رابط إلى الصفحة.

لإزالته: gemini mcp remove quran-gallery.

أو حرّر settings.json بنفسك

أضف الخادم إلى ~/.gemini/settings.json (كل المشاريع) أو .gemini/settings.json (مشروع واحد):

{
	"mcpServers": {
		"quran-gallery": {
			"url": "https://qurangallery.com/mcp/shamela",
			"type": "http"
		}
	}
}

هذا ما يكتبه الأمر. ويعمل "httpUrl": "https://qurangallery.com/mcp/shamela" أيضًا. أبقِ "type": "http" بجانب url، لأن إصدارات Gemini CLI الأقدم تقرأ url وحده نقطةَ اتصال SSE.

أول سؤال تجرّبه

ابحث عن حديث «إنما الأعمال بالنيات» في المجاميع الأصلية، وأخبرني في أي كتاب وطبعة ومجلد وصفحة طُبع. انقل النص العربي بحروفه.

ينبغي أن يستدعي مساعدك shamela_search_library (أو search ثم fetch). وتتضمن النتائج صحيح البخاري، ط السلطانية، الصفحة 1/6، مع رابط إلى تلك الصفحة في قارئ المكتبة. فإن أجاب من ذاكرته بدل ذلك فقل له: «استعمل أداة مكتبة معرض القرآن وانقل ما تعيده.»

يجب أن تكون استعلامات البحث بالعربية؛ فيترجم مساعدك المصطلحات الإنجليزية أولًا (التفاصيل). وتجد أسئلة جاهزة لـ«تخريج الحديث» وتوثيق النصوص ومقارنة التفاسير في قائمة الأدوات الكاملة.

حل المشكلات

  • 400، «schema at properties.transmission.items.items must be a boolean or an object». كان إصدار سابق من خادمنا يرسل مخطط أداة ترفضه واجهة Gemini API، فكان كل سؤال يفشل بهذا الخطأ. وقد أُصلح. أعد تشغيل gemini.
  • 429، «Keyless limit reached». يتيح الاستخدام بلا مفتاح 10 استدعاءات للأدوات في الدقيقة و200 في اليوم لكل عنوان IP. انتظر حسب ترويسة Retry-After، أو أضف مفتاحًا مجانيًا (أدناه). انظر الحدود والأخطاء.
  • 503. الخادم أو المكتبة خلفه غير متاح لوقت وجيز. أعد المحاولة بعد المدة في ترويسة Retry-After. وإن عرض العميل صفر أدوات فانتظر دقيقة ثم أعد الاتصال.
  • الأدوات لا تظهر، أو تنقصك أداة متوقعة. أعد تشغيل gemini ونفّذ /mcp list. فقائمة الأدوات تُقرأ عند البدء.
  • يعرض gemini mcp list الخادم بحالة Disabled، أو تظهر «Gemini CLI is not running in a trusted directory». يعطّل Gemini CLI خوادم MCP في مجلد لم تمنحه الثقة، ولا يجدها gemini mcp remove فيه كذلك. افتح gemini مرة واحدة في ذلك المجلد وامنحه الثقة. وفي سكربت أو مع -p يمكنك بدلًا من ذلك تمرير --skip-trust.
  • يفشل الاتصال فورًا. نقطة الاتصال هي /mcp/shamela. أما /mcp وحده فصفحة ويب لا الخادم.

اختياري: مفتاح مجاني لحدود أعلى

المفتاح ليس مطلوبًا أبدًا. المفتاح المجاني يرفع الحد إلى 60 استدعاءً في الدقيقة ويرفع سقوف نطاق الصفحات المفروضة على الاستخدام بلا مفتاح. أنشئ مفتاحًا من صفحة المطوّرين (Developers) في حسابك بمعرض القرآن (كيف تعمل المفاتيح)، ثم أرسله رمزًا من نوع bearer.

أضفه بالخيار --header (أو -H):

gemini mcp add --transport http quran-gallery 
  https://qurangallery.com/mcp/shamela 
  --header "Authorization: Bearer qg_sk_your_key_here"

وفي settings.json يوضع المفتاح نفسه في كائن headers بجانب url:

{
	"mcpServers": {
		"quran-gallery": {
			"url": "https://qurangallery.com/mcp/shamela",
			"type": "http",
			"headers": { "Authorization": "Bearer qg_sk_your_key_here" }
		}
	}
}

أبقِ المفتاح خارج أي ملف إعدادات تودعه في git.

الخطوات التالية

عدّل هذه الصفحة على GitHub