Pendahuluan

Tatkala melayari laman X (dulunya twitter), saya menjumpai tulisan oleh Abdul Salam al-Shallash, salah seorang developer dari Arab Saudi. Beliau menulis bahawa beliau baru sahaja siapkan satu extension khas Maktabah Shamela yang kita boleh gunakan di Claude.
Justeru extension ni bukan saya yang cipta, saya hanya bantu sampaikan supaya manfaatnya luas kepada penuntut ilmu khususnya.

Extension ni kita panggil sebagai MCP. MCP ialah Model Context Protocol.

Senang cerita, ia macam “jambatan” yang membolehkan AI seperti ChatGPT atau Claude berhubung dengan aplikasi, data dan tools luar.

Shamela MCP ni beza sepenuhnya sebab dia bukan “AI yang cuba faham turath” — dia adalah jambatan terus antara Claude dengan koleksi kitab Shamela yang kita sendiri dah download. Ni yang buat dia rasa macam game changer untuk penuntut ilmu:

• Bukan terhad kepada indeks orang lain — carian adalah atas kitab-kitab yang kita dah download sendiri dalam Shamela, bukan subset terhad yang orang lain decide.

• Reasoning + carian sekali gus — Claude boleh cari, baca, silang rujuk, dan susun jawapan dalam satu perbualan — bukan just “search result” macam search engine biasa. Contoh: nak kumpul takrif satu masalah fiqh merentas 4 mazhab dengan rujukan siap, boleh siap dalam satu request.

• 30 tools yang cover keperluan sebenar tholabul ilmi — dari carian sorfi (morphological), carian mutabiq (tepat dengan tashkil), boolean search (gabung syarat DAN/ATAU/TIDAK dalam satu carian), sampai statistik penyebaran satu perkataan/akar kata merentas kurun — benda yang dulu kena buat manual dalam Shamela app sendiri, sekarang Claude boleh handle terus dalam perbualan.

• Amanah dalam penukilan — tak reka-reka teks, bezakan matan dengan hashiah pentahqiq dengan jelas, declare bila data tak lengkap (contoh: edisi/penerbit yang tak ada dalam database) instead of mengarang.

• Rujukan siap format — lepas jumpa apa yang dicari, terus boleh minta citation siap pakai (gaya Shamela/ringkas/penuh) — jimat masa proses takhrij dan penulisan.

Bak kata orang, ni bukan sekadar “chatbot pandai jawab soalan agama” — ni Claude yang betul-betul boleh baca kitab kita, dengan carian tahap tholabul ilmi (sorfi, boolean [gabung DAN/ATAU/TIDAK], exact match), terus dalam satu perbualan. Untuk sesiapa yang selalu buat tahqiq, bandingkan mazhab, atau susun bahan kajian — ni potential jimat banyak masa berbanding scroll manual dalam app Shamela.

1) Apa benda ni?

Shamela MCP adalah extension (.mcpb) untuk Claude Desktop yang sambungkan Claude terus dengan salinan Maktabah Shamela 4 (المكتبة الشاملة) yang dah install kat komputer kita. Ada 30 tools untuk cari, baca, dan buat rujukan (citation) dari kitab-kitab Islamic yang kita dah download dalam Shamela — semua dalam satu perbualan chat je, tak payah bukak app Shamela berasingan untuk cari.

Prinsip penting:

• Data lokal — extension baca database Shamela terus dari PC kita, takde server pihak ketiga yang campur tangan.

• Read-only — extension ni tak boleh edit/ubah data Shamela kita langsung.

• Amanah rujukan — Claude hanya quote/sandarkan text dari result tool sebenar, tak reka-reka. Matan (teks asal) dan hashiah (footnote pentahqiq) dibezakan dengan jelas.

⚠️ Penting: Sebab extension ni access local file system, dia hanya akan berfungsi dalam Claude Desktop app — TAK boleh guna dalam web/browser (claude.ai) atau app mobile.

Platform disokong: Claude Desktop di Windows dan macOS, dan extension Shamela ni pun declare compatibility untuk dua-dua platform (rujuk manifest dia). Windows lagi banyak ditest, tapi Mac memang officially supported — details kat bahagian 4 di bawah.

2) Cara install extension dalam Claude Desktop

Ni cara umum install mana-mana extension .mcpb dalam Claude Desktop — bukan khusus Shamela je:

1. Download fail .mcpb dari sini (untuk Shamela: laman release GitHub)

   Dah buka page tu scroll sampai bawah bahagian asset. Tekan je fail nama shamela-mcp-1.2.0.mcpb nanti akan terus download.

2. Buka Claude Desktop app, kemudian buka setting:

Settings → Extensions → Advanced settings → Install Extension…

1. (Boleh juga akses Settings dengan klik nama kita kat bucu bawah kiri app)

2. Pilih fail .mcpb yang kita download tadi. Claude akan tunjuk skrin review — details extension, permission yang dia perlukan, dan setting yang boleh dikonfigurasi.

3. Isi setting yang diperlukan (kalau ada — contoh API key, atau untuk Shamela: path folder), then klik Install.

4. Restart Claude Desktop sepenuhnya (bukan just close window — kena quit betul-betul dari system tray/menu bar, then buka semula) supaya extension register dengan betul.

❗ Jangan double-click fail .mcpb terus untuk buka — file association tak reliable (especially kat Windows). Selalu guna route Settings → Extensions di atas.

Lepas install, extension akan muncul dalam senarai Settings → Extensions, dan tools dia boleh di-toggle on/off ikut chat (rujuk bahagian 5 di bawah).

3) Apa yang kita perlukan sebelum install (khusus Shamela)

• Windows 10/11 ATAU macOS

• Maktabah Shamela 4 dah install kat komputer, dan sekurang-kurangnya 1 kitab dah download dalam app Shamela tu (app Shamela stay macam biasa — extension cuma baca database dia)

• Claude Desktop app (bukan claude.ai browser) — download dari laman rasmi Anthropic

4) Setup khusus untuk Mac

Extension ni memang disokong kat macOS (chip Apple Silicon M1/M2/M3/M4 dan chip Intel dua-dua), tapi ada satu isu biasa yang kita kena tahu:

Auto-detect Java kadang tersasar kat Mac. Sebab struktur folder Shamela kat Mac lain dari Windows, field “Java path (advanced)” dalam extension settings mungkin perlu diisi manual:

• Chip Apple (M1/M2/M3/M4): ~/Library/Application Support/Shamela/app/mac/arm64/jre/2/bin/java

• Chip Intel: ~/Library/Application Support/Shamela/app/mac/x86_64/jre/2/bin/java

Cara isi: buka Finder → tekan Cmd+Shift+. untuk tunjuk hidden folder (Library biasanya hidden), atau guna menu Go → Go to Folder… then paste path tu terus. Lepas isi field ni dalam extension settings, tutup Claude Desktop sepenuhnya dan buka semula.

Kalau auto-detect run lancar (folder Shamela ikut default location), kita tak perlu sentuh field ni langsung — biarkan kosong dulu, try dulu sebelum troubleshoot.

5) Wajib buat lepas install: activate tool dalam chat

Extension baru install default dia OFF dalam setiap chat baru. Kena:

1. Buka chat baru

2. Klik icon tools/keys (bawah kotak chat)

3. Toggle ON “Search and Study in the Shamela Library”

4. Sekali je — settings ni akan tersimpan untuk chat lain lepas ni

Setting permission tool (elak Claude asyik tanya “allow” satu-satu)

Secara default, extension local kadang akan minta approval setiap kali Claude nak panggil satu tool baru — annoying bila satu request boleh trigger banyak tool call (contoh: resolve nama, search, get page — 3 approval berasingan). Nak elak ni:

1. Pergi Settings → Extensions

2. Klik extension “Search and Study in the Shamela Library”

3. Cari setting permission (biasa label macam “Always allow” atau “Auto-approve tool calls”)

4. Set ke Allow / Always allow untuk extension ni

Lepas set macam ni, Claude terus jalankan tools tanpa kena stop untuk tanya approval setiap kali — flow chat jadi jauh lebih lancar terutama untuk request yang perlukan banyak tool call sekali gus (contoh: kumpul rujukan merentas beberapa kitab).

⚠️ Set “always allow” ni sesuai untuk extension read-only macam Shamela (dia tak boleh edit/delete apa-apa data). Untuk extension lain yang ada kuasa tulis/hantar/padam data, lebih elok tinjau setiap permintaan dulu sebelum auto-approve.

6) Test install berjaya ke tak

Dalam chat baru, cuba tanya:

“Cari dalam Shamela pasal ‘الكلام’, bagitahu buku mana dan siapa penulis”

Kalau keluar hasil ada nama kitab, penulis, no. muka surat, dan potongan teks — install berjaya.

Boleh juga tanya terus: “Semak extension Shamela, pastikan berfungsi” (guna tool shamela_health — self-diagnostic yang tunjuk versi server, jumlah kitab dalam fahras, dan berapa yang dah download).

7) 30 Tools — ikut kategori

A. Carian dalam kitab

• shamela_search_pages — Cari perkataan dalam matan + hashiah, boleh scope ikut kitab/penulis/kategori/tempoh

• shamela_search_phrase — Cari frasa lengkap ikut susunan tepat, atau kata-kata berdekatan (proximity)

• shamela_search_exact — Carian tepat — ambil kira tashkil, hamzah, sistem nombor

• shamela_search_boolean — Carian logik: DAN / ATAU / TIDAK (all_of / any_of / none_of)

• shamela_search_titles — Cari tajuk bab/fasal dalam kitab

• shamela_search_books — Cari dalam indeks 8500+ kitab (boleh run sebelum download)

• shamela_search_authors — Cari dalam indeks 3100+ penulis (boleh run sebelum download)

B. Al-Quran & Tafsir

• shamela_search_quran — Cari dalam 6236 ayat Quran

• shamela_get_aya — Ambil ayat — rasm imla’i & uthmani

• shamela_get_tafseer_of_aya — Senarai kitab tafsir yang cover ayat tertentu

• shamela_list_tafsirs_for_aya — Status coverage tafsir yang kita download untuk ayat tertentu (jelas: ada/takde entry/tak diketahui)

• shamela_get_tafseer_texts — Tarik teks tafsir dari beberapa sumber sekali gus, disandarkan ke kitab masing-masing

C. Hadith

• shamela_search_hadith — Cari hadith ikut teks, dengan takhrij

• shamela_get_books_for_hadith — Kitab-kitab yang riwayatkan hadith yang sama (guna hadith key)

• shamela_get_page_services — Ayat/hadith/sanad yang disebut dalam satu m/s

D. Baca & navigate

• shamela_get_page — Baca satu m/s penuh (matan + hashiah + komen)

• shamela_get_pages_range — Baca 1–20 m/s berturut-turut

• shamela_get_toc — Fahras kitab dalam bentuk pokok (tree)

• shamela_get_book_section — Baca satu bab/fasal penuh guna title_id dari fahras

• shamela_get_book_parts — Senarai jilid/juzuk kitab

E. Indeks & metadata

• shamela_list_categories — 41 kategori dalam Shamela + bilangan kitab tiap satu

• shamela_list_downloaded_books — Kitab yang betul-betul dah download kat PC kita

• shamela_get_book — Metadata kitab: penulis, kategori, tahun, status

• shamela_get_author — Metadata penulis + senarai kitab dia

• shamela_resolve — Tukar nama Arab separa (contoh “ابن قدامة”) jadi ID kitab/penulis yang tepat

• shamela_get_citation — Format rujukan siap guna — 3 gaya: Shamela, ringkas, penuh

F. Statistik & tempoh

• shamela_root_stats — Sebaran akar kata Arab merentas kategori/kurun/kitab

• shamela_books_by_period — Filter kitab ikut tahun karang atau tahun wafat penulis

G. Diagnostik & panduan

• shamela_health — Self-check — pastikan extension connect & berfungsi

• shamela_guide — Manual penuh dalam Bahasa Arab, terus dalam chat

8) Cara guna — tak payah hafal nama tool

Cakap je dalam bahasa natural (Arab/Melayu/English pun boleh), Claude yang akan decide tool mana nak panggil. Contoh:

• “Cari dalam kitab Ibn al-Qayyim pasal kelebihan selawat ke atas Nabi”

• “Apa isi bab المياه dalam kitab Zad al-Mustaqni’?”

• “Kitab tafsir apa yang cover ayat Kursi?”

• “Berapa banyak akar kata صبر muncul dalam kitab-kitab akidah?”

• “Bagi citation format untuk m/s 17 kitab ni”

Nak tahu apa extension ni boleh buat, tanya je: “Apa yang shamela tools boleh buat?”

9) Cara pastikan Claude betul-betul guna extension (bukan jawab dari ingatan)

Macam mana nak tahu Claude memang cari dalam Shamela, bukan jawab ikut apa yang dia dah “tahu”?

Dalam chat, lepas Claude jawab, scroll naik sikit — kalau dia betul-betul call tool, mesti ada satu tool-call block (boleh klik/expand) yang tunjuk nama tool (contoh shamela_search_pages) dan parameter yang dihantar, dengan label extension “Search and Study in the Shamela Library” sekali. Biasanya ada sedikit jeda/loading sebelum jawapan keluar — tanda dia fetch data dulu.

Kalau takde tool-call block macam tu, Claude jawab terus dari pengetahuan umum dia — bukan dari database Shamela sebenar, dan berisiko silap/reka tanpa kita sedar.

Cara arah Claude sentiasa guna extension:

1. Explicit dalam mesej — paling senang, cakap terus: “guna Shamela tools untuk cari ni” atau “jangan jawab dari ingatan, cari betul-betul dalam database Shamela”.

2. Custom Instructions (automatik, applies semua chat) Pergi Settings → Profile, isi custom instructions — contoh:

“Untuk sebarang soalan pasal kitab turath, ayat Quran, atau hadith, sentiasa guna Shamela tools untuk verify dulu sebelum jawab. Jangan jawab dari ingatan sendiri je.”

1. Project instructions (disyorkan untuk sesi kajian khusus) Buat satu Project khas untuk tholabul ilmi/kajian, letak instruction yang sama kat situ. Kelebihan dia — instruction automatik apply setiap kali buka chat baru dalam Project tu, tak payah taip berulang setiap sesi.

⚠️ Nota: walaupun dah set instruction macam ni, Claude tetap akan skip tool call untuk soalan yang jelas takde kaitan dengan kitab (contoh soalan basic am). Instruction ni paling berkesan untuk kekalkan disiplin bila topik memang perlukan rujukan turath.

10) Prompt Contoh — Optimise Setiap Tool

Senarai prompt untuk setiap satu daripada 30 tools, supaya kita boleh explore penggunaan penuh extension ni:

A. Carian dalam kitab

1. search_pages — “Cari perkataan ‘الوسوسة’ merentas semua kitab akidah yang aku ada”

2. search_phrase — “Cari frasa tepat ‘من كان يؤمن بالله واليوم الآخر’ — bukan perkataan berselerak”

3. search_exact — “Cari ‘قُرْء’ dengan tashkil tepat — jangan campur dengan bentuk lain”

4. search_boolean — “Cari m/s yang sebut ‘الصلاة’ DAN ‘الجماعة’ tapi TIDAK sebut ‘القصر’”

5. search_titles — “Cari tajuk bab yang ada perkataan ‘الطهارة’ merentas kitab fiqh aku”

6. search_books — “Cari kitab pasal ‘أصول الفقه’ dalam katalog Shamela — tak kisah dah download ke belum”

7. search_authors — “Cari penulis dengan nama mengandungi ‘ابن رجب’”

B. Al-Quran & Tafsir 8. search_quran — “Cari semua ayat yang sebut ‘الصبر’ dalam Quran” 9. get_aya — “Bagi ayat 255 Surah Al-Baqarah, rasm uthmani” 10. get_tafseer_of_aya — “Kitab tafsir apa yang cover ayat Kursi?” 11. list_tafsirs_for_aya — “Untuk ayat 286 Al-Baqarah, tafsir mana dalam koleksi aku yang ada entry, mana yang tak diketahui” 12. get_tafseer_texts — “Tarik tafsir ayat ni dari 3 sumber berlainan sekali gus, banding pandangan diorang”

C. Hadith 13. search_hadith — “Cari hadith pasal ‘من حسن إسلام المرء تركه ما لا يعنيه’” 14. get_books_for_hadith — “Hadith niat ni, kitab-kitab mana lagi riwayatkan versi yang sama?” 15. get_page_services — “M/s ni ada sebut ayat/hadith apa? Bagi breakdown penuh”

D. Baca & navigate 16. get_page — “Baca penuh m/s 45 kitab ni, termasuk hashiah pentahqiq” 17. get_pages_range — “Baca m/s 100 sampai 110 kitab ni berturut-turut” 18. get_toc — “Tunjuk fahras penuh kitab Zad al-Ma’ad” 19. get_book_section — “Baca bab pasal solat jenazah penuh, guna title_id dari fahras tadi” 20. get_book_parts — “Kitab ni ada berapa jilid? Senaraikan”

E. Indeks & metadata 21. list_categories — “Senaraikan 41 kategori Shamela, tunjuk mana paling banyak kitab” 22. list_downloaded_books — “Apa je kitab yang aku dah download setakat ni?” 23. get_book — “Bagi metadata penuh kitab ni — penulis, tahun, kategori” 24. get_author — “Ibn Hajar al-Asqalani — bila wafat, berapa kitab dia dalam koleksi aku?” 25. resolve — “Nama ‘ابن قدامة’ ni — ada berapa penulis match, mana yang paling terkenal?” 26. get_citation — “Bagi citation format penuh untuk m/s ni, siap sedia untuk footnote”

F. Statistik & tempoh 27. root_stats — “Root ‘يقن’ — macam mana sebaran dia merentas kategori kitab yang aku ada?” 28. books_by_period — “Senaraikan kitab tafsir yang dikarang antara kurun 4H-6H je”

G. Diagnostik & panduan 29. health — “Semak status extension Shamela — connect elok ke tak?” 30. shamela_guide — “Tunjuk manual penuh Shamela tools dalam Bahasa Arab”

11) Troubleshooting — masalah biasa

Tools tak muncul lepas install / tiba-tiba stop function Tutup Claude Desktop sepenuhnya (right-click system tray icon → Quit), buka semula. Ni fix dua-dua situasi: install baru yang belum aktif, atau registration lama yang tersangkut.

Extension installed tapi Claude tak guna tools dalam chat Extension baru default OFF setiap chat. Toggle “ON” kat icon tools/keys bawah kotak chat (rujuk bahagian 5 di atas).

Tools run dalam satu chat, tak run dalam chat lain Sesetengah interface Claude Desktop tak load extension local. Cuba chat text biasa baru dari window utama app.

Error “Shamela not found” Auto-detect gagal jumpa lokasi install. Masuk settings extension, isi manual path folder (yang ada sub-folder database dan app).

Error “Java bundled tak jumpa” (Mac) Isi field “Java path (advanced)” dalam extension settings:

• Chip Apple: ~/Library/Application Support/Shamela/app/mac/arm64/jre/2/bin/java

• Chip Intel: ~/Library/Application Support/Shamela/app/mac/x86_64/jre/2/bin/java

Carian bagi 0 result padahal perkataan wujud

• Try minta “carian sorfi” (morphological search) — cover semua bentuk kata (يكتب، كاتب، مكتوب...)

• Guna wildcard * dan ? dalam perkataan

• Untuk match tashkil/hamzah/nombor tepat, minta “carian mutabiq” (shamela_search_exact)

Kitab baru download tapi tak muncul Restart Claude Desktop — extension buka fahras masa mula sesi je.

Error “Kitab belum download” Kitab tu wujud dalam fahras tapi belum download kat PC. Buka app Shamela, download dari situ dulu.

Nak report bug Attach log dari:

• Windows: folder %APPDATA%\Claude\logs

• Mac: folder ~/Library/Logs/Claude

Kalau masalah connection/install (tools langsung tak muncul) → attach mcp.log. Kalau masalah satu tool specific (error masa search/baca) → attach fail yang mula dengan mcp-server- untuk Shamela.

Report di: https://github.com/alhoqbani/shamela-mcp/issues

12) Limitasi penting (kena faham)

• Carian hanya cover kitab yang dah download — result kosong tak bermakna takde dalam kitab lain yang belum download

• Extension tak menghukum sahih/dhaif hadith sendiri — dia bawa apa yang ada dalam hashiah pentahqiq je

• Fahras kaitan ayat-tafsir adalah “curated index” yang tak cover semua tafsir yang kita download — tool shamela_list_tafsirs_for_aya akan state status jelas untuk setiap kitab (ada entry / takde entry / status tak diketahui)

• Data penerbitan (edisi, penerbit, pentahqiq) selalunya tak lengkap dalam database Shamela — citation akan declare data yang missing, tak reka-reka

13) Privasi

Sumber data 100% lokal — extension buka database Shamela kat PC kita secara read-only, dan extension sendiri tak connect ke server luar. Nota: apa yang tools tarik keluar (teks kitab) akan jadi sebahagian dari perbualan kita dengan Claude, dan perbualan Claude diproses melalui rangkaian mengikut dasar app biasa — jadi “lokal” di sini describe sumber data, bukan laluan perbualan.

14) Apa yang baru dalam v1.2.0

• 10 tools baharu (dari 20 → 30): carian frasa, carian tepat, carian boolean (gabung DAN/ATAU/TIDAK), carian hadith, statistik akar kata, filter ikut tempoh, status tafsir per-ayat, tarik teks tafsir pelbagai sumber, self-diagnostic, dan panduan terbina-dalam

• First-use lebih laju (dulu ~12 saat delay, sekarang engine ready awal)

• Carian Quran fix isu perkataan macam “الصبر” bagi 0 result sebab beza “ال” ta’rif

• Teks panjang sampai dalam bahagian tersusun (tak dipotong tiba-tiba)

• Data kitab lebih tepat (status “dibaca” vs “diindeks tanpa m/s”, pentahqiq/penerbit auto-extract dari nama kitab tanpa reka)

• Fix stuck bila browse banyak kitab

• Serasi dengan install Shamela versi terkini

Full changelog: https://github.com/alhoqbani/shamela-mcp/releases/tag/v1.2.0

⚠️ Disclaimer

Hakikat sebenar extension ni: ia sekadar tool carian yang lebih advance berbanding carian Shamela biasa — dia boleh sorfi, boolean, exact match, dan navigate fahras dengan pantas. Setakat itu je. Dia bukan tool analysis/istinbat yang absah dalam ilmu agama Islam, sebab ilmu agama ada disiplin dan kaedahnya sendiri (usul fiqh, mustalah hadith, qawaid tafsir, dll) yang tak boleh digantikan dengan pattern-matching AI. Claude boleh bantu cari dan susun apa yang tertulis dalam kitab — tapi proses faham, tarjih, dan istinbat hukum tetap kena ikut disiplin ilmu yang sepatutnya, bukan output extension ni.

Untuk siapa: tool ni sesuai untuk penuntut ilmu yang dah ada asas — dah faham struktur kitab turath, dah biasa dengan istilah usul & mustalah, dan tahu bezakan matan dengan hashiah. Bagi yang belum ada asas tu, extension ni berisiko tersasar penggunaan — contoh: terus ambil hasil carian macam “jawapan hukum” tanpa faham konteks, sanad, atau khilaf ulama di sebalik teks tu. Kalau baru nak mula belajar, elok mula dengan guru/kitab metodologi dulu, bukan bergantung kat tool carian macam ni sebagai sumber utama faham agama.

Sebagai penuntut ilmu, kita tetap kena:

• Semak semula setiap teks yang ditarik terus dari kitab asal (Shamela app / cetakan bermuktabar), jangan terus salin-tampal apa yang Claude bagi tanpa verify

• Rujuk kembali kepada ahli ilmu untuk isu hukum, tarjih antara pendapat, atau apa-apa masalah yang perlukan istinbat — extension ni cuma bantu cari & susun, bukan berfatwa

• Faham limitasi tool — carian terhad kepada kitab yang kita dah download, indeks tafsir/hadith adalah “curated” (tak lengkap 100%), dan status sahih/dhaif hadith bukan Claude yang tentukan, dia bawa apa ada dalam hashiah pentahqiq je (rujuk bahagian 12 - Limitasi Penting)

• Berhati-hati dengan citation — data penerbitan (edisi/penerbit/pentahqiq) kadang tak lengkap dalam database, jadi selalu cross-check sebelum guna dalam penulisan rasmi

Ringkasnya: guna benda ni untuk percepatkan proses cari & navigate, bukan untuk gantikan proses tahqiq, istifta’, dan disiplin ilmu yang sepatutnya.

⚙️ Limitasi Teknikal — Loophole & Mistake Yang Kena Kita Sedar

Beberapa perkara teknikal yang berpotensi mengelirukan kalau kita tak faham cara tool ni run:

1. “Carian frasa” vs “carian biasa” — boleh confuse shamela_search_pages (default) buat carian AND per-perkataan, bukan frasa exact. Kalau minta cari “الأعمال بالنيات”, dia boleh return m/s yang ada dua-dua perkataan tu berselerak dalam ayat lain — bukan semestinya frasa tepat. Untuk carian frasa betul-betul kena guna shamela_search_phrase khas.

2. Carian sorfi (morphological) — bukan 100% tepat Tool shamela_root_stats sendiri declare accuracy dia ~80% untuk Arab klasik. Kalau nak buat statistik/kajian rasmi berdasarkan angka ni, kena declare limitasi tu, jangan present macam angka mutlak.

3. Statistik “coverage_capped” — angka jadi floor, bukan exact Bila hits lebih 5000, breakdown ikut kategori/kurun/kitab akan capped. Perbandingan antara dua topik guna root_stats boleh underestimate dan mengelirukan kalau salah satu topik jauh lebih capped dari yang lain.

4. Boolean search — exclusion (none_of) tak menyeluruh Carian none_of (NOT) cuma applied dalam “candidate window” yang capped per term — page yang ada perkataan excluded tu masih boleh terlepas keluar dalam result kalau ia di luar window tersebut. Result nampak “bersih” padahal tak semestinya 100% tersaring.

5. Fahras tafsir “curated” — silence ≠ tiada shamela_list_tafsirs_for_aya sendiri warn: kalau satu kitab tafsir tak muncul dalam status “ada entry”, tu bukan bukti kitab tu takde bahas ayat tersebut — mungkin just tak diindeks. Jangan guna “tiada dalam senarai” sebagai hujah “tafsir ni tak sentuh ayat ni.”

6. Hadith — tool tak nilai sahih/dhaif Extension bawa apa yang ada dalam hashiah (footnote pentahqiq) je. Kalau muhaqqiq silap grading, atau kitab takde footnote takhrij, Claude takkan “tahu”. Output extension bukan hukum hadith yang authoritative — tetap kena rujuk kitab takhrij/mustalah yang muktabar.

7. Nombor muka surat — automatik Shamela vs cetakan sebenar README declare: kalau page numbering tu automatik dari Shamela (bukan manual match cetakan), ia boleh tak sama dengan m/s cetakan sebenar yang orang guna untuk rujuk. Jangan terus salin nombor m/s untuk citation akademik tanpa cross-check dengan cetakan asal.

8. shamela_resolve — partial name match boleh silap orang Nama serupa/parsial boleh resolve ke penulis/kitab yang salah, especially nama yang overlap (contoh gaya “ابن سيرين”, “ابن رجب”). Sentiasa verify ID yang betul, jangan terus percaya match pertama yang keluar.

9. Risiko “Always allow” pada permission “Always allow” (rujuk bahagian 5) assume extension memang read-only macam yang author declare. Kalau install .mcpb dari sumber lain (bukan release rasmi GitHub yang signed), takde jaminan ia betul-betul read-only. Set “always allow” cuma untuk source yang verified/official.

10. Data stale antara sesi Fahras dibuka sekali je bila app start. Kalau download kitab baru dalam Shamela app semasa Claude Desktop tengah run, kena restart app baru nampak kitab baru tu. Kalau tak restart, Claude boleh confidently declare “kitab ni takde” padahal baru je habis download.

Moga-moga bermanfaat buat penuntut ilmu.

Panduan ni disediakan berdasarkan dokumentasi rasmi extension (README + release notes v1.2.0) dan pengalaman guna sebenar. Rujuk repo GitHub untuk update terkini: https://github.com/alhoqbani/shamela-mcp

Sudah lama saya menulis di pelbagai tempat — blog, Facebook, Telegram dan media sosial yang lain.

Masalahnya, semakin banyak menulis, semakin berselerak pula tulisan-tulisan itu. Ada yang tenggelam dalam timeline, ada yang sukar dicari semula, malah ada yang saya sendiri sudah terlupa pernah menulisnya.

Sebab itu saya memilih untuk mula menulis di Substack.

Saya mahu menjadikan ruang ini sebagai tempat untuk mengumpulkan tulisan-tulisan saya, sama ada tulisan lama yang masih relevan mahupun tulisan baru selepas ini.

Tentang hadis, ilmu agama, buku, kehidupan dan apa sahaja yang saya rasa bermanfaat untuk dicatat dan dikongsi.

Anggaplah ini sebuah rumah baru untuk tulisan-tulisan saya.

Sedikit demi sedikit, insya-Allah saya akan kumpulkan semuanya di sini.

Kalau tuan/puan berminat untuk mengikuti tulisan-tulisan saya dari semasa ke semasa, bolehlah subscribe. Insya-Allah, setiap tulisan baru akan terus sampai kepada tuan/puan.

Moga ada manfaatnya.

Bismillah. Kita bermula sekali lagi.