Grounding rules: citing classical Islamic texts with MCP
The citation contract for answers built on the Quran Gallery MCP server: quote only tool results, separate matn from footnote, never invent edition data.
On this page
An assistant connected to the library can still write a bad answer. These rules are the contract that keeps an answer checkable. The server also publishes them to your client as the resource qurangallery://grounding-rules, and its instructions point the model at the same behaviour.
The rules
- Quote only what a tool returned. Attribute a text to a book only if it came back in a tool result. Do not complete a quotation, an isnād or a wording from general knowledge.
- Keep the main text and the footnote apart. Every passage says where the words were found in
matchedIn:body,footnote,bothorunknown. The body is the author’s text (the matn / المتن). A footnote is the editor’s or commentator’s voice. Never present a footnote as the author’s words (Reading a result). - Printed page is not Shamela numbering.
printedPageis the volume and page as that printing paginates it, such as1/ 6. When the library numbers a book automatically, the page is a Shamela page number, not the printed one, and must be labelled that way. Cite the edition with the page: the same page number means different text in a different edition. - Never invent publication data.
edition,editorandpublisherappear on a passage only when the library has them. When they are missing, say they are not available. Do not fill them from memory. - Say how the match was made.
relaxedToTokens: truemeans the exact phrase was not found, only its words. That supports “these words appear on this page”, not “this wording is printed here”. - A miss is scoped. “Not found in these eight collections” is a finding. “Does not exist” is not one the tools can support.
- No grading and no rulings. The server never grades a hadith as ṣaḥīḥ, ḥasan or ḍaʿīf, and gives no fatwā. If a source quotes a grading, report it as that source’s statement, with the book and page.
- Credit the source. Every passage carries a
sourceUrlof the formhttps://qurangallery.com/maktabah/book/{bookId}/{pageId}. Link it, and credit shamela.ws as the origin of the text.
What a passage carries
| Field | Use |
|---|---|
book, author, authorDied | Name the work and its author; authorDied is in AH. |
printedPage | The printed volume and page. |
edition, editor, publisher | Only when present. Never guess them. |
matchedIn, matchQuality | Main text vs footnote; exact vs loose match. |
bookId, pageId | The Shamela identifiers of the page. |
sourceUrl | The page in the Maktabah reader, to verify the quotation. |
arabic | The passage, verbatim. Quote it as it stands. |
A good citation reads: al-Bukhārī, Ṣaḥīḥ al-Bukhārī, ṭ. al-Sulṭāniyya, 1/6 (main text), Maktabah link. A bad one names a book and a hadith number the model remembered.
Checking an answer
Take the sourceUrl or the bookId and pageId, open the page, and compare. Your assistant can do it for you with shamela_read (unit: 'page'), or turn a printed citation back into a page with shamela_cite (mode: 'printed_page') (the full tool surface).
What the server does not guarantee
It guarantees that a passage, book and page are real and were retrieved. It does not guarantee that the sentence your assistant builds around them is a fair reading. See What the MCP server does.
Next steps
Questions
What are the grounding rules for citing Islamic texts with an AI?
Quote only what a tool returned, keep the main text and the footnote apart, label printed pages correctly, never invent edition data, say how the match was made, treat a miss as scoped, give no gradings or rulings, and credit the source.
Where does the MCP server publish the grounding rules?
As the resource qurangallery://grounding-rules, and the server's instructions point the model at the same behaviour.
Does the MCP server grade a hadith as sahih or daif?
No. It never grades a hadith and gives no fatwa. If a source quotes a grading, report it as that source's statement, with the book and page.
What should a citation from the MCP server include?
The book, author, edition, printed volume and page, whether the words are in the main text or a footnote, and the sourceUrl link to the Maktabah reader, crediting shamela.ws as the origin of the text.
Can the server stop my assistant from misquoting a passage?
No. It guarantees that the passage, book and page are real and were retrieved, not that the sentence your assistant builds around them is a fair reading.