HadithDB

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, full hadith-detail lookup, and Quran audio tools.

Substantive research is available through research_islamic_topic and research_quran_ayah. The topic tool takes a question, short Arabic/English queries, optional known hadith_references to anchor the evidence, and depth (brief, standard, or deep). It gathers discovery candidates, exact Quran/tafsir and hadith records, commentary from distinct works, and reports linked by verified internal references. Source numbers alone are never treated as cross-collection identities.

For ayah explanations, call research_quran_ayah with surah and ayah. Standard depth requests Tabari, Ibn Kathir and Qurtubi; deep adds Baghawi, Saadi and Ibn Ashur. Missing sources are reported rather than silently replaced. tafsirs overrides this selection. Read the returned texts, then call again with short grounded concepts to research relevant Quran/tafsir, hadith and shuruh. This is an assistant workflow within one turn, not a user follow-up. The tool does not pretend to infer semantic concepts on the server.

Dossiers distinguish direct tafsir, exact reports, source-linked reports, and conceptual search candidates. They return per-call found, searched_no_match, not_searched, or unavailable states, omissions and explicit next steps. Dossiers include selected source fields and bounded excerpts: discovery text is capped at 500 characters per field, retrieved source text at 3500, with truncation flags and exact lookup identifiers. They are not exhaustive surveys or generated rulings. A 25-second total deadline and depth-dependent call/source limits bound work; inspect coverage and retrieve truncated or omitted sources when consequential. Research depth does not dictate answer length.

list_hadith_commentaries, search_hadith_commentary and lookup_hadith_commentary expose the existing shuruh catalog and index. Search supports an exact commentary source alias and/or associated hadith reference; lookup uses an entry id. Compact hadith details now include research_inventory with the complete attached commentary list, work counts, and verified related references. Every detail profile also includes metadata.grades (all stored grader opinions), metadata.narrators (including reliability and death_text, the stored death year or date description), and metadata.related_reports (deduplicated collection:number references only). Compact metadata.sharh lists commentary identities without text; use the commentary lookup tool for complete text.

After deploying schema changes, update the published plugin/connection metadata and verify the tools visible in a fresh client session against tools/list. Publishing the JSON schema URL alone does not refresh an installed plugin’s schema snapshot. In particular, lookup_hadith_detail must expose response_profile to clients as it does on the server.

The public tool schema is available at GET /mcp-server/schema.json, linked from /mcp-server. It includes the server and protocol versions and the same tool definitions returned by MCP tools/list, including input/output schemas and annotations. It is generated from the running server’s definitions and requires no MCP initialization or authentication.

get_quran_audio returns a full-surah audio_url, a playback_url with a seconds-based media fragment, passage start_ms / end_ms, and ordered ayah segments with millisecond boundaries. For example, {"surah":2,"ayah_from":255,"ayah_to":257} defaults to Juhani; add reciter to select an alias or exact name from list_quran_reciters. Omit ayah_to for one ayah. Supply the first and last ayah for a whole surah; call once per surah for a passage spanning surahs. Incomplete timing coverage returns an error. These tools supply playback data; the client must play the URL, seek to the start, and stop at the end. Media-fragment support depends on the player.

Quran navigation tools expose the stored Mushaf layout and editorial headings:

• lookup_quran_page: pass page, or surah and ayah, for edition information, ayah ranges and word boundaries, overlapping headings, and stored introductions. Its page overview is assembled from source headings, not a separately authored narrative summary. Ayahs can span pages; word boundaries identify the portion here.
• list_quran_sections: pass surah to discover passage (level 2) and subsection (level 3) identities, bilingual titles, introductions, and exact ayah ranges. Follow next_offset; default limit is 25, maximum 100.
• lookup_quran_passage: pass surah and section (optionally subsection), or surah and ayah to resolve the containing passage. Returns parent/child relationships and Mushaf page links as well as the source heading record.

These tools preserve absent language fields as null. response_profile controls per-heading introduction length: compact 1000, default 6000 characters per language, or full without truncation. Introductions describe the entire heading range, which may extend beyond a requested page. Titles and ranges are preserved. An assistant can write a narrative page summary from this source material when asked, clearly distinguishing its synthesis from the stored editorial text.

Arabic and English are exposed separately when the underlying record provides both languages; unavailable language fields are returned as null rather than synthesized. Long tafsir and hadith-detail tools accept compact, default, and full response profiles. Hadith detail defaults to compact; default adds bounded scholarly attribution and commentary, while full is the explicit complete-provenance mode. Search tools return exact-size pages, pagination metadata, and opaque cursors; Quran search merges translation hits under each canonical ayah. Pagination reports whether its total is exact; total_available is null while the backend has only fetched enough data to prove another page exists. Searches reject logical offsets beyond 500, scan at most six underlying pages per call, and enforce a ten-second deadline. list_tafsirs also returns total, has_more, and an opaque query-bound cursor. Quran ayat, Quran search results, hadith search results, and hadith-detail records expose bilingual, text, text_arabic, text_english, and truncated. Full-profile hadith-detail sharh entries retain their existing text and text_en source fields and additionally expose language-explicit fields. The bounded default profile exposes the language-explicit commentary fields without duplicating the original long text fields.

The endpoint accepts JSON-RPC 2.0 requests for initialize, ping, tools/list, tools/call, skills/list, skills/get, and resources/read. It advertises five source-aware research skills through OpenAI's static MCP skill-import extension. It does not create sessions, so clients should not expect an Mcp-Session-Id response header. Browser preflight requests are supported with OPTIONS /mcp; the public edge owns the complete CORS response for this path, while the application validates browser origins and native clients may omit Origin. 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. Add browser origins with the comma-separated MCP_ALLOWED_ORIGINS setting. See MCP data handling for the redacted audit-log contract and retention setting.

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 co