🕌 Kuran MCP Server

AlQuran.cloud API’sini kullanarak Kuran verilerine erişim sağlayan Model Context Protocol (MCP) server’ı.

📋 Özellikler

• 📖 Sure Listesi: Tüm 114 surenin listesini getir
• 📚 Edisyon Yönetimi: Farklı dillerde ve çevirilerde Kuran edisyonları
• 🔍 Ayet Erişimi: Belirli ayetleri referans ile getir
• 🌐 Çoklu Çeviri: Aynı ayeti birden fazla çeviriden karşılaştır
• 🔎 Arama: Kuran’da kelime ve ifade arama
• 📖 Cüz Erişimi: 30 cüzün herhangi birini getir
• 🤲 Secde Ayetleri: Tüm secde ayetlerini listele
• 📄 Sayfa Erişimi: Mushaf sayfalarına göre erişim
• ℹ️ Meta Veriler: Kuran yapısı hakkında detaylı bilgiler

🚀 Kurulum

Gereksinimler

• Python 3.8+
• pip

Adımlar

1. Depoyu klonlayın:

git clone <repository-url>
cd quran_mcp

2. Bağımlılıkları yükleyin:

pip install -r requirements.txt

3. MCP Server’ı çalıştırın:

python server.py

🛠️ Kullanım

MCP Tools

1. list_all_editions()

Tüm mevcut Kuran edisyonlarını listeler.

# Tüm edisyonları getir
editions = await list_all_editions()

2. list_editions_by_language(language: str)

Belirli bir dildeki edisyonları listeler.

# Türkçe edisyonları getir
turkish_editions = await list_editions_by_language("tr")

3. list_surahs()

Tüm surelerin listesini getirir.

# Sure listesi
surahs = await list_surahs()

4. get_surah_text(surah_number: int, edition: str)

Belirli bir sureyi getirir.

# Fatiha suresini Türkçe çeviri ile getir
fatiha = await get_surah_text(1, "tr.diyanet")

5. get_verse(reference: str, edition: str)

Belirli bir ayeti getirir.

# Ayetel Kürsi'yi getir
ayetel_kursi = await get_verse("2:255", "quran-uthmani")

6. search_in_quran(keyword: str, surah: str, edition_or_language: str)

Kuran’da arama yapar.

# "Allah" kelimesini ara
results = await search_in_quran("Allah", "all", "en")

Desteklenen Edisyonlar

Arapça

• quran-uthmani: Uthmani script
• quran-simple: Basitleştirilmiş Arapça

Türkçe

• tr.diyanet: Diyanet İşleri Başkanlığı çevirisi
• tr.vakfi: Türkiye Diyanet Vakfı çevirisi

İngilizce

• en.asad: Muhammad Asad çevirisi
• en.pickthall: Marmaduke Pickthall çevirisi
• en.sahih: Sahih International çevirisi

🧪 Test

Test sayfasını açmak için test.html dosyasını bir web tarayıcısında açın. Bu sayfa:

• Tüm API endpoint’lerini test etmenizi sağlar
• Gerçek zamanlı sonuçları görüntüler
• Modern ve kullanıcı dostu arayüz sunar

Test Özellikleri

1. Sure Listesi Testi: Tüm sureleri listeler
2. Edisyon Testi: Dil bazlı edisyon filtreleme
3. Sure Getirme: Belirli sureleri farklı edisyonlardan getir
4. Ayet Erişimi: Referans ile ayet getirme
5. Çoklu Çeviri: Aynı ayeti birden fazla çeviriden karşılaştır
6. Arama Testi: Kelime bazlı arama
7. Cüz Erişimi: Cüz bazlı okuma
8. Secde Ayetleri: Özel ayet kategorileri

📚 API Referansı

Bu MCP server AlQuran.cloud API kullanır. Desteklenen endpoint’ler:

• /v1/edition - Edisyon listesi
• /v1/surah - Sure listesi
• /v1/surah/{number}/{edition} - Belirli sure
• /v1/ayah/{reference}/{edition} - Belirli ayet
• /v1/search/{keyword}/{surah}/{edition} - Arama
• /v1/juz/{number}/{edition} - Cüz
• /v1/sajda/{edition} - Secde ayetleri
• /v1/meta - Meta veriler

🔧 Geliştirme

Yeni Özellik Ekleme

1. app.py dosyasına yeni fonksiyon ekleyin
2. server.py dosyasına MCP tool olarak kaydedin
3. test.html dosyasına test bölümü ekleyin

Hata Ayıklama

# Verbose mod ile çalıştır
python server.py --verbose

# Logları kontrol et
tail -f mcp.log

📄 Lisans

MIT License - Detaylar için LICENSE dosyasına bakın.

🤝 Katkıda Bulunma

1. Fork yapın
2. Feature branch oluşturun (git checkout -b feature/amazing-feature)
3. Commit yapın (git commit -m 'Add amazing feature')
4. Push yapın (git push origin feature/amazing-feature)
5. Pull Request açın

📞 İletişim

• GitHub Issues: Hata raporları ve özellik istekleri
• Email: [email@example.com]

🙏 Teşekkürler

• AlQuran.cloud - Ücretsiz Kuran API’si sağladığı için
• MCP Community - Protocol geliştirme için

Not: Bu proje eğitim ve araştırma amaçlıdır. Kuran metinlerinin doğruluğu için güvenilir kaynaklara başvurun.