People do not type canonical slugs. Accepting `bukhari`, `sahih-bukhari`, `Sahih al-Bukhari` and `sahih_bukhari` as the same collection is the difference between a citation tool that works mid-sentence and one that returns errors until you look up its identifiers. The other well-judged decision is the fallback: when the embedding provider refuses, search degrades to keyword rather than failing, so a quota problem does not become a blank answer. Building the database first is the real cost of entry.
An MCP server over a local SQLite database of hadith text in Arabic and English, plus the pipeline that builds it from the community hadith-json dataset. The design goal is citation safety: the assistant retrieves from a real corpus and cites it, rather than reconstructing a narration from training data.
- The grounding rules returned once per session, so the assistant knows how it is expected to quote before it starts — `fetch_grounding_rules`
- A hadith fetched by global id, or by collection plus number — including a string range like `1-5` — with cross references optionally attached; the collection argument accepts canonical slugs, common variants and human names alike — `fetch_hadith`
- Search that defaults to semantic, with `mode=keyword` for SQL substring matching or `mode=both`; if the embedding provider returns a quota, billing or rate-limit error, it falls back to keyword search rather than failing — `search_hadith`
- Algorithmic similarity matches for a hadith across collections, built from cosine similarity with narrator-aware scoring — `fetch_cross_references`
- An interactive reader rendered in hosts that support MCP apps, always returning a plain-text fallback with the same citation URLs so other hosts still get a readable answer — `show_hadith`
- A small REST surface over the same store for non-MCP use — `/api/collections`, `/api/hadith/{id}`, `/api/search`
- Optional per-client rate limits and an LRU query cache to hold down cost
The database has to be built before the server is useful: clone the hadith-json dataset locally and run the build script against its `db/by_book` directory. Semantic search additionally needs `OPENAI_API_KEY` and a database whose rows carry embeddings — the embedding pass is a long, checkpointed run and can be done on a separate machine, with checkpoints replayed afterwards. Keyword search works without either. Install with a virtualenv and `pip install -e ".[dev]"`; then `hadith-mcp --transport stdio` for desktop clients or `--transport http`. `HADITH_MCP_DB_PATH` overrides the database location and takes precedence over the config file. The pyproject name is `hadith-mcp` (0.1.0). Upstream attribution to the dataset authors and Sunnah.com is expected if you ship something on top of it.
One command plus a key — pip install -e ".[dev]", then supply credentials