HadithDB

HadithDB (Hadith Unlocked) is a website for reading, searching, and citing the Quran and ḥadīth. You can browse it online at https://hadithunlocked.com.

Every record keeps the original Arabic text alongside an English translation where one is available, together with chapter listings and grading information. For ḥadīth, the chain of narrators (isnād) and the report itself (matn) are stored separately so each can be read and searched on its own.

MCP server

HadithDB exposes a read-only, stateless Streamable HTTP MCP transport at POST /mcp. After this version is deployed, the public endpoint will be https://hadithunlocked.com/mcp. It provides Quran and tafsir lookup/search, hadith search, and full hadith-detail lookup tools.

Text fields are returned in full. Arabic and English are exposed separately when the underlying record provides both languages; unavailable language fields are returned as null rather than synthesized or omitted. Quran ayat, Quran search results, hadith search results, and hadith-detail records expose bilingual, text, text_arabic, text_english, and truncated. Hadith-detail sharh entries retain their existing text and text_en source fields and additionally expose the same language-explicit fields, with their combined value in text_combined.

The endpoint accepts JSON-RPC 2.0 requests for initialize, ping, tools/list, and tools/call. It does not create sessions, so clients should not expect an Mcp-Session-Id response header. Browser preflight requests are supported with OPTIONS /mcp; other HTTP methods return 405.

curl https://hadithunlocked.com/mcp \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"example","version":"1.0.0"}}}'

The endpoint has a 64 KiB request limit and a per-IP rate limit. Override the defaults with MCP_RATE_LIMIT_WINDOW_MS and MCP_RATE_LIMIT_PER_IP. Internal tool requests use the current request host by default; staging deployments can override the backing sites with HADITHDB_MCP_HADITH_BASE_URL and HADITHDB_MCP_QURAN_BASE_URL.

What's New

Recent work has improved the reading, browsing, and search experience across the site:

• Reading the Quran — move naturally between Passage, Ayat, Mushaf, Practice, and Mudhakkir views while the site keeps your place. You can like, comment on, bookmark, and share a passage, move easily between verses and sections, and use the page-faithful Mushaf with database-backed spaced repetition.
• The 15-line Mushaf — read all 604 pages in a responsive, page-faithful Digital Khatt layout with infinite scrolling, Quranic surah headers, interactive words and ayah markers, page bookmarks, passage-aware coloring, and continuous recitation.
• Commentary and translation — full-page commentary and translation views, tabs for switching between works, authored book and surah introductions, hover explanations, dynamic translation selection, and the option to show Arabic and English side by side. You can turn individual works on or off and choose the order they appear in.
• Quran audio — choose a reciter, begin from a selected ayah, continue across page boundaries, repeat a passage or subsection, and control playback speed without losing synchronized ayah highlighting or translation captions.
• Search — a site-wide search panel switches between ḥadīth and Quran + Tafsīr while remembering a separate query for each. It supports canonical Quran ordering, Arabic RTL input, virtual collections, book-group shortcuts, per-work filters, and unified suggestions for surahs, ayat, translations, tafsīr, and ḥadīth.
• Enriched ḥadīth details — individual reports can include multiple scholarly grades, report and chain classification, a linked narrator timeline, uncommon-word definitions, sourced explanations, and references to similar or supplementary transmissions.
• Outline navigation — responsive section menus and sticky desktop rails follow the current chapter, passage, subsection, or metadata section and expose nearby headings for faster movement through long works.
• Sharing — responsive Quran and ḥadīth share cards support editable copy, text-size controls, selectable translations, Copy text, Copy image, and the device share sheet.
• MCP access — a read-only Streamable HTTP endpoint exposes Quran, tafsīr, ḥadīth search, and full ḥadīth-detail tools to compatible clients without creating server-side sessions.
• My Settings — separate starting points for ḥadīth and Quran, remembered commentary, translation, and reciter preferences, and bookmarked passages and Mushaf pages saved for later.

Hadith Features

• Browse source books and thematic virtual collections with bilingual chapter and section navigation, stable book:number citations, and JSON, TSV, EPUB, or Markdown output where available.
• Search the whole ḥadīth library or narrow it to individual books and the Sahihayn, Four Sunan, Six Books, or Nine Books groups. Virtual collections remain searchable alongside their source books.
• Read Arabic isnād and matn separately from the English translation. Report attribution and chain categories identify material such as prophetic, companion, or successor reports and connected or interrupted chains when that metadata is available.
• On enriched detail pages, compare scholarly grading opinions, follow a vocalized narrator-by-narrator isnād with biographical links and reliability notes, open definitions of uncommon Arabic terms, read Arabic or English sharḥ, and follow similar-report references back into the library.
• Supplementary source transmissions are linked to their primary local report instead of being presented as unrelated duplicate records.
• Like, bookmark, comment on, cite, and share reports. The share editor can resize or omit language blocks and copy either formatted text or a generated image on desktop and mobile.
• Administrators can revise text and headings in place, manage scholarly grades and sourced explanations, link similar reports, enrich metadata from configured sources, and refresh the affected search and rendered caches without changing the public citation.

Quran Unlocked

Read the Quran as a book, explore it as a study text, and hear it as a continuous recitation—all in one place. Quran Unlocked combines a responsive 15-line Mushaf with word-level learning, passage structure, trusted translations and tafsīr, personalized audio, and tools for saving and sharing what matters.

Open the Mushaf and begin where you left off. Tap a word for its meaning, select an ayah to read its translation, or let the recitation carry you seamlessly across pages. Switch to Practice to test recall against the same 15-line page layout, or move instantly to a focused ayah or structured passage without losing your place.

Quran Features

Five connected reading modes

• Passage presents the Quran in titled sections and subsections for thematic reading.
• Ayat focuses the reading experience on individual verses and the ayah hero view.
• Mushaf reproduces the familiar 15-line, page-by-page reading experience.
• Practice keeps the Digital Khatt Mushaf font and 15-line page layout while replacing ordinary words with underlined blanks. The basmalah and ayah markers remain visible.
• Mudhakkir tests due ayat using an ayah-level spaced-repetition schedule. Learning ayat enter the queue first and progress through short new-card steps before graduating to Good.
• The mode links, page subtitle, URL, previous/next links, and related passage automatically follow the content currently in view during infinite scrolling.
• Direct navigation is available by surah, ayah, passage, subsection, juz, manzil, Mushaf page, and search result.

A responsive Digital Khatt Mushaf

• All 604 pages use Digital Khatt Quran text in a page-faithful 15-line layout.
• Pages load continuously with vertical infinite scroll; after page 604, reading can continue again from page 1.
• The layout scales for desktop, portrait phones, and landscape phones without changing through the normal text-size controls or bleeding beyond the page.
• Quranic surah headers use the QCF header font. A new surah opens with its header and basmalah kept with the beginning of the surah; Surah 9 correctly omits the basmalah.
• Subtle inner-edge shading distinguishes odd and even pages like an open printed book.
• Alternating black and saddle-brown text reveals h3 subsection boundaries while preserving the Quranic styling of ayah markers.
• Each page identifies its page number, juz, surah number, and Arabic surah name. Page, juz, and surah numbers are directly editable, while the custom surah picker opens at the current surah.
• The page footer links the passage and subsection titles that actually begin on that page, making the Mushaf’s thematic structure visible without repeating earlier headings.
• /quran/page resumes at the bookmarked Mushaf page, or page 1 when no page bookmark exists.

Practice view

• Open a Mushaf page with ?memorize, such as /quran/page/1?memorize, select Practice from the Quran reading-mode controls, or use the Practice item after Tafsir in the Quran menu.
• Hidden words retain their exact Digital Khatt width and placement and are individually underlined, preserving the page-faithful 15-line layout. Surah headers, the basmalah, and ayah markers remain visible.
• Clicking a hidden word reveals it; clicking that visible word hides it immediately. When Word auto-hide is enabled, a clicked word fades back to an underlined blank after two seconds.
• The chevron beside each āyah marker includes Play and Reveal in Practice mode. Reveal changes to Hide while that āyah is visible. Play uses the reader's default reciter, automatically reveals the complete āyah, plays only that one āyah, and shows its translation in the audio marquee; neither action changes memorization or FSRS state. Play remains available during Mudhakkir, while the separate Reveal and Hide actions are omitted there.
• Clicking an ayah marker toggles that complete ayah between visible text and blanks without changing the other ayat.
• Alt-clicking, Option-clicking, Command-clicking, or Control-clicking an ayah marker toggles that ayah and all earlier ayat on the Mushaf page between visible text and blanks.
• Icon-only Page and Word auto-hide controls appear at both the top and bottom of each page. The bottom controls replace the passage and subpassage headings in Practice mode.
• The Page control reveals every word on that page or returns the page to blanks. Hiding also clears individual word and ayah reveals.
• The Word auto-hide control determines whether individually clicked words disappear after two seconds or remain visible. Auto-hide is off by default and remains a page-local display control; it is not stored as memorization progress in the browser.
• The plus and minus controls reveal the next hidden ayah or hide the most recently revealed ayah, one ayah at a time.
• Each page keeps its own state as additional pages load through infinite scrolling, and Practice mode remains active through page, surah, juz, URL, and previous/next navigation.
• Audio, reciter and translation controls, the translation marquee, and word-translation tooltips are intentionally omitted so the view remains focused on recall.

Ayah-level memorization and spaced review

Memorization identity is the surah and ayah reference, not a Mushaf page. Page numbers remain useful for navigation, but every ayah has its own lifecycle, schedule, and append-only review history. Untouched ayat behave as Later without creating 6,236 rows for every user.

The six visible memorization states use the same recall language as the review grades. Automatic recovery is stored internally but presented inside Hard:

State	Meaning
Later	Memorization has not started, or the ayah was removed from active memorization
Learning	Memorization has started but the complete ayah is not yet independently recitable
Hard	The ayah is memorized but recall is fragile, so it remains scheduled with shorter review intervals; automatic recovery after a failed Good review is included here
Good	The complete ayah can be recalled independently and remains under spaced review
Easy	The ayah is known by heart, considered memorized, and not scheduled for regular review
Paused	Learning or review is temporarily suspended without deleting its schedule or history

• Signed-in readers make one initial self-assessment for an untouched Later āyah: Learn, Hard, Good, or Easy. After enrollment, review grades manage Learning, Hard, and Good; individual āyah, page, surah, and progress-group controls expose Easy, Paused, and Later. A complete page or surah can receive another initial bulk assessment only while all of its āyāt are Later. Signed-out readers are not shown a control that could imply local persistence.
• A new account with no Quran memorization rows starts with all 18 āyāt of Surahs 1, 113, and 114 in Learning. Initialization is idempotent and never adds these starter āyāt to an account that already has any memorization state recorded.
• An initial Learning assessment creates a New FSRS 6 card, admits it gradually within the Learning and overall session caps, and gives admitted Learning cards the highest queue priority. Again resets learning progress, Hard keeps it Learning, two successful Good reviews graduate it, and Easy graduates it immediately. The first intervals are approximately 10 minutes to 1 day for Again, 1 to 2 days for Hard, 3 to 4 days for Good, and 6 to 7 days for Easy before FSRS adapts them from review history. The Learning summary tile on Memorization Progress filters to groups containing Learning ayat and links each group directly to its first Learning ayah in Practice mode.
• An initial Hard assessment initializes the ayah like a Hard review result, with lower stability, higher difficulty, and a short first interval. Hard āyāt remain eligible for regular review. One Easy or two consecutive Good reviews can promote Hard to Good once its FSRS difficulty is 6 or lower; difficulty greater than 6 keeps it Hard.
• An initial Good assessment confirms that the complete ayah can be recited independently. FSRS initializes it like a Good result, records the memorization date, and schedules its first recall from that strength. Good is not a terminal archive: the scheduler continues adapting the interval after each review.
• An initial Easy assessment initializes the FSRS estimate like an Easy result, records a memorization date, clears the next review date, and keeps the āyah out of regular review. It can still be included deliberately in a custom Surah review session.
• A scheduled Good or Hard āyah also graduates automatically to Easy after a Good or Easy review when its FSRS stability is greater than 730 days and difficulty is below 2. Graduation clears its next review date. Existing cards that already satisfy both thresholds are migrated to Easy. A user may also mark an individual enrolled āyah as Easy directly.
• Hard combines deliberately fragile memorization, any scheduled āyah with an FSRS recall-difficulty score greater than 6, and scheduler-driven recovery after Again on a Good āyah. Recovery remains distinct internally for scheduling, but it uses the Hard label, red color, count, and progress filter. Successful reviews return it to Good only after calculated difficulty reaches 6 or lower.
• Later, Easy, and Paused āyāt never enter regular Learning or Mudhakkir queues. Regular review for a surah follows that same rule. An all-āyāt review deliberately enrolls Later āyāt in the selected surah as Learning and can include Easy and Paused āyāt in the session. After enrollment, the only manual changes are Easy, Paused, or Later, and all preserve review history. Internal recovery remains distinct from Later and is presented as Hard because it represents previously memorized recall that now needs strengthening.
• Practice and Mudhakkir use consistent accents for Learning, Hard, Good, Easy, and Paused. Hard is red, Good is blue, and Easy is green, matching the review-grade buttons. Internal recovery uses the Hard presentation. The regular Mushaf does not show memorization-state highlights. Where accents are shown, the full ayah is treated without reducing Arabic-text contrast, and the marker also exposes a textual state so color is not the only cue.

Select Mudhakkir to open /quran/review, which combines Memorization Progress with the session launcher. Progress reports Due now, Learning, Hard, Good, Easy, Paused, and Later against the canonical 6,236 ayat rather than counting stored rows alone. Due now includes initialized FSRS cards whose scheduled timestamp has arrived. Learning includes both ungraded FSRS New cards and Learning cards with review history, since New is an internal FSRS phase rather than a separate memorization state. Automatic recovery remains internal and is included in the Hard count, filter, color, and page summaries. Hard, Good, and Easy are initialized immediately from the user's stated memory strength. The active-progress table groups Mushaf pages beneath each surah and shows a shared page under every surah it contains; each row counts only that surah's ayat on the page and shows its per-stage totals and Arabic opening words without a translation.

The top of the signed-in Mudhakkir page shows a one-year review activity heatmap, today's reviewed āyāt and elapsed review time, daily average, percentage of days learned, longest streak, and current streak. Scheduler, review, and session timestamps are stored as UTC. Due checks compare UTC instants, while displayed dates, heatmap days, streaks, and the set of āyāt revealed as reviewed today use the current browser's timezone. This keeps late-evening reviews on the user's local day while progress remains consistent across devices.

Signed-out visitors see a concise Quran memorization introduction with a sign-in invitation, a plain-language explanation of how adaptive spaced review keeps Quran hifz fresh, progress-tracking benefits, and a link to explore the Mushaf. Memorization Progress and review-session controls are shown only after authentication.

During a recall attempt, the sticky controls record a result rather than changing a permanent status directly:

Mudhakkir pages after page 1 show the final Arabic line of the preceding Mushaf page in a compact, always-visible continuity strip above the current page. The strip is non-interactive and excluded from concealment, grading, memorization-state controls, and audio selection.

Result	Scheduling meaning
Again	Recall failed; keep Learning or Hard in its current state, move Good into Hard recovery, and allow one retry near the end of this session
Hard	Recall succeeded independently with significant hesitation; use a shorter next interval
Good	Recall succeeded with ordinary effort; use the normal next interval
Easy	Recall was fluent and effortless; use a longer next interval
Skip	Advance without changing lifecycle, strength, schedule, or review history

The help text reserves Again for an attempt that required reading the ayah or receiving its missing continuation; Hard still means the complete ayah was recalled independently. The first Again queues the same āyah once near the end of the session. A second Again records the lapse without another retry, so the same āyah can receive Again at most twice per session and cannot create an unlimited loop.

Regular review sessions are persisted and bounded. They admit eligible Learning, Hard, and Good āyāt, including automatic Hard recovery, allocate the overall limit fairly across nonempty categories, and present Learning first. Fragile Hard āyāt and previously Good āyāt in Hard recovery share one combined Hard cap. Newly enrolled, ungraded Learning cards are immediately included in Due now, but enter each session gradually under the Learning cap. Any one-time Again retries follow the original queue; Easy āyāt are not admitted to regular sessions. An āyah cannot reappear after a grade or Skip unless it entered that retry slot. My Settings → Quran Memorization and the Mudhakkir settings modal configure the maximum total āyāt per session (default 10), optional time budget, and a collapsed Advanced session limits group containing Learning, Hard, and Good caps plus queue order.

Page and surah review

The Start Review menu offers a custom Surah Review session. Its autocomplete accepts English names, Arabic names, Arabic or Latin surah numbers, and alternate names. Suggestions use the Quran search result style and show the surah number, English name, Arabic name, and total āyāt.

Practice mode also places a Mudhakkir button beneath each Mushaf page. Its contextual dialog offers Just this page or A surah. Just this page creates a persisted page-review session containing the āyāt on that exact Mushaf page, including pages shared by multiple surahs. A surah opens the same searchable Surah Review workflow without requiring the user to return to Memorization Progress first.

After choosing a surah, the user chooses one of two review types. Regular review uses only that surah's eligible Learning, Hard, and Good āyāt, follows their existing due schedules and regular session limits, and does not enroll or change untouched āyāt. All-āyāt review enrolls every missing or Later āyah in the surah as Learning and adds the complete surah to a persisted Quran-order session. Already-enrolled Learning, Hard, Good, Easy, and Paused āyāt receive no enrollment write: their existing state, schedule, and history are preserved when the session is created, and they are simply added to its queue. The user can review āyah by āyah or passage by passage. Passage review uses the most specific Study range containing the current āyah—an h3 range when available, otherwise its h2 range. The passage is only an āyah batch: the chosen result is recorded as a separate review event for every included āyah, and each āyah receives its own FSRS calculation, state, and next-review schedule.

Page-review and all-āyāt sessions are not constrained by Due now, regular category caps, or the optional time budget. They continue until every included āyah has been graded or skipped. Regular review for a surah uses the normal scheduler and its limits. Again, Hard, Good, and Easy are recorded as real FSRS assessments, so grading an Easy or Paused āyah in an all-āyāt session can return it to scheduled memorization according to the result. Skip advances without changing the āyah's state, schedule, or review history.

The Mushaf review footer can pause a page or surah review session without losing its current āyah or queue position, or end it while preserving completed review history. Memorization Progress lists the active session together with paused sessions. Continuing the active session or switching to a paused session is explicit; switching atomically pauses the current session before resuming the selected one. Any active or paused session can be ended. Ending closes its remaining queue while retaining completed FSRS review history.

FSRS 6 settings are available in My Settings and in a modal on /quran/review: