Tafsir MCP

---

🌙 نبذة

خادم Model Context Protocol (MCP) يوفّر وصولاً علمياً موثّقاً للقرآن الكريم لأي مساعد ذكي يدعم MCP (Claude Code، Claude Desktop، VS Code، وغيرها).

كل البيانات مراجعة ومعتمدة من مركز تفسير للدراسات القرآنية.

---

✨ المميزات

• 📖 6,236 آية كاملة بالرسم العثماني
• 📚 5 تفاسير كلاسيكية: الطبري · ابن كثير · البغوي · السعدي · الميسر
• 🌍 المختصر في التفسير بـ3 لغات (عربي، إنجليزي، بنغالي)
• 🔤 77,432 كلمة بتحليل لغوي شامل (إعراب، صرف، جذر، رسم)
• 🔍 1,891 جذر قابل للبحث والإحصاء
• ⚡ بحث FTS5 سريع مع تطبيع عربي كامل (بدون تشكيل)
• 🎵 اختلاف القراءات لكل آية وكلمة
• 📜 أسباب النزول بالإسناد الكامل (201 آية)
• 📊 إحصاءات تفصيلية لكل سورة وصفحة مصحف
• 🛡️ حماية صارمة من الهلوسة (Pydantic v2 validation)
• 📴 يعمل دون إنترنت بعد التثبيت

---

🚀 التثبيت السريع

لمستخدمي Claude Code:

claude mcp add tafsir --scope user -- uvx tafsir-mcp

للتثبيت اليدوي:

pip install tafsir-mcp
# أو
uvx tafsir-mcp

عند أول تشغيل، سيُحمَّل ملف البيانات (~214 MB) من Hugging Face تلقائياً ويُخزَّن في ~/.cache/tafsir-mcp/.

للمطوّرين (من المصدر):

git clone https://github.com/tafsircenter/tafsir-mcp
cd tafsir-mcp
cp /path/to/quran.db data/quran.db   # أو: export TAFSIR_DB_PATH=/path/to/quran.db
uv sync
uv run tafsir-mcp

---

🌐 الاستضافة والنشر

الإنتاج مُستضاف على Fly.io (region bom/Mumbai) خلف النطاق الرسمي https://mcp.tafsir.net/mcp (MCP-over-HTTP، فحص صحة على /health). أي عميل يدعم HTTP transport يتّصل مباشرةً دون تثبيت محلي.

نسخة Hugging Face Space السابقة أصبحت أرشيفًا خاصًّا (Private، غير حيّة) — انظر docs/ADR/0001-fly-over-hf-space.md.

---

🔧 ربط Claude Desktop

أضف إلى ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tafsir": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/YOUR_USERNAME/projects/quranic-scholar-mcp",
        "run",
        "tafsir-mcp"
      ]
    }
  }
}

---

🧰 الأدوات المتاحة (13 أداة)

---

📋 الموارد والقوالب

الموارد (Resources)

قوالب الدراسة (Prompts)

---

📚 مصادر التفسير

---

🗂️ بنية المشروع

src/tafsir/
├── server.py          # FastMCP entry point
├── db.py              # SQLite read-only connection
├── data_loader.py     # DB path resolver + auto-download
├── models.py          # Pydantic models + attributions
├── normalize.py       # Arabic text normalization
├── tools/             # 13 MCP tools
├── resources/         # 3 MCP resources
└── prompts/           # 5 study prompt templates

---

🧪 الاختبارات

uv run pytest tests/ -v
# 35 tests — all pass

---

🔒 الأمان

• قاعدة البيانات تُفتح للقراءة فقط: mode=ro + PRAGMA query_only=ON
• جميع مدخلات المستخدم عبر ? placeholders — لا SQL injection
• الأدوات لا تصل للشبكة (openWorldHint=False)

---

📜 الترخيص

• الكود: MIT License — Ahmed Eid, Tafsir Center for Quranic Studies
• قاعدة البيانات: CC BY 4.0 — يجب نسبة المصدر لمركز تفسير

---

🏛️ الجهة الراعية

هذا المشروع رعاية ودعم مركز تفسير للدراسات القرآنية. البيانات القرآنية مراجعة وموثّقة من قِبل الباحثين العلميين في المركز.

📧 [email protected]

---

🌙 About

A Model Context Protocol (MCP) server providing scholarly, certified access to the Holy Quran for any MCP-compatible AI assistant (Claude Code, Claude Desktop, VS Code, etc.).

All data is reviewed and certified by Tafsir Center for Quranic Studies.

✨ Features

• 📖 6,236 ayahs in Uthmani script
• 📚 5 classical Arabic tafsirs: Tabari · Ibn Kathir · Baghawi · Saadi · Muyassar
• 🌍 Trilingual Mukhtasar (Arabic, English, Bengali)
• 🔤 77,432 words with full linguistic analysis (i'rab, sarf, root, rasm)
• 🔍 1,891 roots searchable with statistics
• ⚡ FTS5 search with full Arabic normalization (diacritic-free)
• 🎵 Qira'at variants per ayah and word
• 📜 Asbab al-nuzool with full isnad (201 ayahs)
• 📊 Detailed statistics per surah and mushaf page
• 🛡️ Hallucination protection (strict Pydantic v2 validation)
• 📴 Fully offline after installation

🚀 Quick Install

# Claude Code
claude mcp add tafsir --scope user -- uvx tafsir-mcp

# pip / uvx
pip install tafsir-mcp
uvx tafsir-mcp

On first run, the database (~214 MB) is downloaded automatically from Hugging Face and cached at ~/.cache/tafsir-mcp/.

🧰 Available Tools (13)

📜 License

• Code: MIT — Ahmed Eid, Tafsir Center for Quranic Studies
• Quranic Data: CC BY 4.0 — attribution to "Tafsir Center for Quranic Studies" required

🏛️ Sponsor

Sponsored by Tafsir Center for Quranic Studies.

📧 [email protected] · GitHub Issues