Skip to content

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

  1. 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.
  2. Keep the main text and the footnote apart. Every passage says where the words were found in matchedIn: body, footnote, both or unknown. 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).
  3. Printed page is not Shamela numbering. printedPage is the volume and page as that printing paginates it, such as 1/ 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.
  4. Never invent publication data. edition, editor and publisher appear on a passage only when the library has them. When they are missing, say they are not available. Do not fill them from memory.
  5. Say how the match was made. relaxedToTokens: true means the exact phrase was not found, only its words. That supports “these words appear on this page”, not “this wording is printed here”.
  6. A miss is scoped. “Not found in these eight collections” is a finding. “Does not exist” is not one the tools can support.
  7. 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.
  8. Credit the source. Every passage carries a sourceUrl of the form https://qurangallery.com/maktabah/book/{bookId}/{pageId}. Link it, and credit shamela.ws as the origin of the text.

What a passage carries

FieldUse
book, author, authorDiedName the work and its author; authorDied is in AH.
printedPageThe printed volume and page.
edition, editor, publisherOnly when present. Never guess them.
matchedIn, matchQualityMain text vs footnote; exact vs loose match.
bookId, pageIdThe Shamela identifiers of the page.
sourceUrlThe page in the Maktabah reader, to verify the quotation.
arabicThe 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.

Edit this page on GitHub