# MCP for developers: Grounding rules: citing classical Islamic texts with MCP

Source: https://qurangallery.com/docs/mcp/grounding-rules

> The citation contract for answers built on the Quran Gallery MCP server: quote only tool results, separate matn from footnote, never invent edition data.

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](https://qurangallery.com/docs/mcp/reading-results)).
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

| 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](https://qurangallery.com/docs/mcp/tools)).

## 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](https://qurangallery.com/docs/mcp/overview).

## Next steps

- [Open Quran Gallery MCP](https://qurangallery.com/mcp)
- [Verify an AI-quoted passage against the printed page](https://qurangallery.com/docs/mcp/verify-a-quotation)
- [Search the main text or the footnotes of a Shamela book](https://qurangallery.com/docs/mcp/search-main-text-or-footnotes)
- [MCP server for Islamic texts: what it does](https://qurangallery.com/docs/mcp/overview)
