hadith-mcp

Model Context Protocol (MCP) server and data pipelinefor servingcanonical hadith text(Arabic and English) to assistants in acitation-safeway—similar in spirit toquran-mcp: fetch from a real corpus instead of quoting from model memory.

- Hadith textcomes from the communityhadith-jsondataset (scraped fromSunnah.com), which aligns with the broadersunnah-com/ Quran Foundation ecosystem—the same family of sources behindquran-mcp.
- Architecture and patternsare inspired byquran-mcp(FastMCP, grounding mindset, tooling layout).

Large reference treeshadith-json-main/andquran-mcp-master/are listed in.gitignore. Clone or unpackhadith-jsonlocally (for example ashadith-json-main/) or pass--data-dirtobuild_db.py.

python3 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" cp .env.example .env # set OPENAI_API_KEY for embedding steps

1) Build the database (without calling OpenAI)

Point--data-dirat your localhadith-jsondb/by_bookdirectory.

python scripts/build_db.py --fresh --skip-embed --skip-cross --skip-provenance \ --data-dir ./hadith-json-main/db/by_book

2) Embeddings (long run; use a separate machine if you prefer)

Safe defaults:batch size 1,commit every 10 rows,sleep between calls, optionalJSONL checkpointfor safety.

python scripts/embed_hadith.py \ --db-path ./data/hadith.db \ --checkpoint ./data/embeddings_checkpoint.jsonl \ --batch-size 1 \ --commit-every 10 \ --sleep-between-batches 0.15

Replay checkpoints into the DB when needed:

python scripts/merge_embedding_checkpoints.py --db-path ./data/hadith.db \ ./data/embeddings_checkpoint.jsonl --only-missing

3) Cross-references and provenance (local CPU)

Donotre-runbuild_db.pywithout--freshafter embedding unless you intend to re-import JSON (that path canoverwriterows and clearembedding). Instead:

python scripts/compute_crossref.py --db-path ./data/hadith.db

For asingle-machinefull build (import + embed + cross + provenance), runbuild_db.pyoncewithout--skip-embed/--skip-cross/--skip-provenance, and pass embedding pacing flags as needed (python scripts/build_db.py --help).

4) MCP server (stdio for Cursor / Claude Desktop)

From the repo root withdata/hadith.dbpresent (or setHADITH_MCP_DB_PATH):

hadith-mcp --transport stdio # or: python -m hadith_mcp --transport stdio # or: fastmcp run hadith_mcp.server:mcp

Optional--config config.ymlsetsdatabase.pathrelative to the config file.HADITH_MCP_DB_PATHoverrides both.

HTTP / SSE / streamable HTTP (see FastMCP docs for host/port env vars):

Tools (summary):fetch_grounding_rulesreturns full text once per MCP session (then a short repeat unlessforce_full=True); pass returnednonceonly when you need to disambiguate errors.fetch_hadithaccepts globalhadith_idorcollection+hadith_number(int, or string range like1-5) with optionalinclude_cross_references. Thecollectionargument is resolved through aforgiving slug matcher— canonical slugs (bukhari), common variants (sahih-bukhari,Sahih al-Bukhari,sahih_bukhari), and human names (Sunan Abu Dawud,Musnad Ahmad,40 Hadith Nawawi) all map to the same row.search_hadithdefaults tosemanticsearch (loads all embeddings at startup, embeds the query with the configuredquery embedding model); usemode=keywordfor SQL substring search, ormode=both. Semantic search needsOPENAI_API_KEYand a database whose rows include embeddings. If OpenAI returns quota/billing/rate-limit errors (or the query vector size does not match the DB), the serverfalls back to keyword searchinstead of failing.fetch_cross_referencesreturns algorithmic similarity matches across collections for a given hadith.show_hadithopens aninteractive Hadith ReaderMCP App in supported hosts (ChatGPT Developer Apps, Claude with app support, etc.);prefer calling it with the canonicalhadith_idreturned byfetch_hadith/search_hadith/fetch_cross_references—collection+hadith_numberand free-textqueryare supported fallbacks, and the tool always returns a plain-text fallback so non-App hosts still get a readable answer with the same citation URLs. The top-level MCP instructions nudge assistants toward the two-step flow (look up first, thenshow_hadith(hadith_id=…)) to avoid guessing slugs or numbers from memory. Optionalper-client rate limitsand anLRU query cachereduce cost and abuse (seeconfig.yml/.env.example).

Citation URLs.fetch_hadith,search_hadith,fetch_cross_references, andshow_hadithattach aurlfield to each hadith or cross-reference row pointing at the search frontend (https://search.hadith-mcp.org/?id=<db_id>by default, overridable viaHADITH_SEARCH_APP_URL). The server's MCP instructions tell assistants to always surface this link alongside citations and to never fabricate links to external hadith sites (sunnah.com, etc.).

Interactive reader (show_hadith).The tool binds to aui://hadith.htmlresource served astext/html;profile=mcp-app. The HTML template lives atsrc/hadith_mcp/assets/hadith_app.htmland isfully self-contained— inline CSS, inline app logic, system fonts only, zero CDN fetches, zero cross-origin iframes. The@modelcontextprotocol/ext-appsSDK isvendoredundersrc/hadith_mcp/assets/ext-apps.bundle.js(rewritten to a classic script that attaches towindow.__hadithMcpSdk) and spliced into the template at startup, so the whole widget ships as a single HTML document. Refresh the pinned SDK version withpython3 scripts/fetch_ext_apps.py --version <x.y.z>. The resource meta setsui.csp.resourceDomains = [](no external origins at runtime) and intentionallyomitsui.domainbecause ChatGPT and Claude require incompatible formats for that field (ChatGPT wants anyhttps://…URL; Claude requires a sha256-derived.claudemcpcontent.comsubdomain and errors with "App domain configuration is invalid" on anything else) — both hosts work correctly when the field is omitted. Once mounted, the embedded app callsfetch_hadithandsearch_hadithover the MCP bridge (no extra HTTPS) to let users open cross-references and switch between detail and search views without LLM round-trips. A single-hadithshow_hadithcall renders pure card chrome (no search bar); calls with aqueryor no arguments render the search-bar + results UI.

The repo ships a small static search app insearch/and an HTTP REST surface on the same FastMCP process, intended to be deployed as two subdomains (e.g.search.hadith-mcp.organdapi.hadith-mcp.org) with nginx / Caddy proxying/api/to the FastMCP port.

- Frontend (search/):plain HTML/CSS/JS, no build step. Bootstraps from?id=<db_id>or?q=<query>on load, so the URLs MCP tools emit resolve directly. The API base defaults tohttps://api.hadith-mcp.org; override in the browser viawindow.HADITH_API_BASE(set beforescript.jsloads) for local or staging deployments.search/sitemap.xmlis a sitemap index; per-collection URL lists live undersearch/sitemaps/— regenerate withpython3 scripts/generate_search_sitemap.pyafter rebuilding the database.
- REST endpoints(same process, mounted via@mcp.custom_route):

- GET /api/collections→{collections: [...]}
- GET /api/hadith/{hadith_id}→{hadith: {...}}
- GET /api/hadith/{slug}/{id_in_book}→{hadith: {...}}
- GET /api/search?q=&limit=&collection=→{results, mode, note}; semantic by default with the same keyword fallback behavior as the MCP tool. SharesHADITH_MCP_RATE_LIMIT_SEARCH_RPMand the query cache with MCP clients, so one budget covers both surfaces.
- GET /api/stats(optional trailing slash) → aggregate search/lookup counts, unique visitors, uptime. Landing + search UIs trysame-originGET /api/statsfirst, then the public API host; re-copysite/andsearch/when you update those pages, or the browser will run old HTML/JS.

- Secrets:.envis gitignored; see.env.exampleforOPENAI_API_KEYand MCP tuning (HADITH_MCP_QUERY_EMBEDDING_MODEL,HADITH_MCP_RATE_LIMIT_SEARCH_RPM,HADITH_MCP_SEARCH_CACHE_MAX).
- Hosted MCP:PutOPENAI_API_KEYon the server only if you accept paying for query embeddings; tuneHADITH_MCP_RATE_LIMIT_SEARCH_RPM(e.g.30–120) and cache size. The query modelmust match the dimension of vectors stored inhadith.db(this repo’s build usestext-embedding-3-large/ 3072). A cheaper OpenAI model generally meansrebuilding the databasewith that model so dimensions align.
- Artifacts:Otherdata/.dbfiles and embedding checkpoint globs are gitignored; this repo tracksdata/hadith.db(Git LFS) plusdata/SHA256SUMSfor verification (cd data && sha256sum -c SHA256SUMS).
- Embeddings:Rows with empty English narrator and text still embed usingArabictext when present. Long inputs are clipped withtiktoken(cl100k_base) to stay under the8192-tokenAPI limit, with a further shrink ladder if a row still hits length errors.
- Count rows without thesqlite3CLI:
python -c "import sqlite3; c=sqlite3.connect('data/hadith.db'); print(c.execute('SELECT COUNT() FROM hadiths WHERE embedding IS NULL').fetchone()[0])"

- Software in this repository(Python, scripts, and documentation we added) is licensed underGNU General Public License v3.0 only(SPDX:GPL-3.0-only).
- Hadith text and other upstream materialremain under their original terms (hadith-json,Sunnah.com). Our GPL applies to our code, not to a relicensing of that content; keep attribution and follow upstream rules when you redistribute data or excerpts.

- Checksum:data/SHA256SUMSlistshadith.db. After cloning or downloading the database, runcd data && sha256sum -c SHA256SUMS.
- Signing (optional):A detachedGPGorSigstoresignature over the checksum file or the database proves who published the bytes and that they were not altered afterward. Signing does not certify scholarly accuracy of every narration or automated cross-reference.
- Reproducibility:For audits or rebuilds, record thehadith-jsonrevision, this repo’sgitrevision, the embeddingmodel id, and script versions you used.

An academic paper search server powered by the OpenAlex API.