quran-usage-guide

# quran.ai MCP Usage Guide ## 1. Core Rules ### Canonical Or Nothing — STRICT, NO EXCEPTIONS **NEVER quote, paraphrase, or summarize Quran text, translation, or tafsir from your own memory or training data.** If you do not have the canonical data in your context, you MUST call the appropriate tool (`fetch_quran`, `fetch_translation`, `fetch_tafsir`) to retrieve it. Do NOT ask the user whether to fetch — just fetch it. Do NOT offer a "general summary from knowledge" or "from what I recall" as an alternative — that is **forbidden**. Canonical sources are: - **quran.ai MCP tool data**: `fetch_*` / `search_*` results - **Dynamic context**: markdown blocks with YAML frontmatter containing `source`, `type`, and `ayahs` headers already in your context, typically originating from MCP App widget context (`updateModelContext`). Widget metadata (page number, selected verse) in `structuredContent` is **not** canonical data — still fetch if only metadata is present. If the user asks for exact wording (Arabic or translation), you MUST use canonical sources above. If the user asks about meaning, tafsir, or context, you MUST fetch tafsir first — do not interpret from memory. ### Session Start: Grounding Rules First **Your first call in any conversation MUST be `fetch_grounding_rules`.** This returns the citation, attribution, and faithfulness rules that govern every subsequent tool call. The response also includes a `grounding_nonce` — extract and pass it to subsequent tool calls via the `grounding_nonce` parameter to suppress redundant grounding payload injection and save tokens. ``` fetch_grounding_rules() → read rules, extract grounding_nonce fetch_quran(surah=1, grounding_nonce="<nonce>") → tokens saved ``` The nonce is optional — omitting it simply means the full grounding rules (~2KB) are injected into every gated tool response as before. Retrieve this full guide text at any time via `fetch_skill_guide`. ### Tafsir-Grounded Interpretation If you make any interpretive/explanatory claim (what a verse "means", "implies", "is about", "is referring to", "the lesson is", etc.), you MUST ground it in tafsir text that you fetched (`fetch_tafsir`) or already present in context. If you have not fetched tafsir or do not have it in present context, restrict yourself to: - Quoting the Arabic and/or translation (canonical text) - Simple restatement of the translation text only (no added interpretive inference) ## 2. Tafsir Discipline ### Sourcing: Single vs Multi-Source **Single-source tafsir** is acceptable for: - Simple clarification of a verse's meaning - The user explicitly requests a specific scholar **Multi-source tafsir** (2–3 editions) is expected for: - Theological interpretation - Legal implications (ahkam) - Historical context (asbab al-nuzul) - Contested or nuanced meanings - Comparative analysis When selecting multiple sources, prefer diversity across approaches — don't pick editions that all specialize in the same thing. Across a conversation, do not automatically reuse the same set of mufassirin if other suitable methodological lenses are available. Arabic tafsir editions are always valuable — fetch and translate them even when the user's language is not Arabic. ### Selection Gate Before calling `fetch_tafsir`, one of these MUST be true: 1. The user named a specific mufassir or edition → use it 2. You have already called `list_editions(edition_type="tafsir")` in this conversation, read the "Choose for..." descriptions, and can state why each selected edition fits the user's question If neither is true, call `list_editions` first. Do not skip this step — the corpus includes 13+ editions across narration-based, linguistic, legal, rhetorical, structural, and reflective approaches. Picking without reading the descriptions means you are guessing, not choosing. Pay attention to `avg_entry_tokens` when selecting: prefer concise editions (~250 tokens/entry) for quick clarifications or tight context budgets, and reserve exhaustive editions (2000+ tokens/entry) for deep comparative readings where the user wants full scholarly depth. Selection rationale template (state briefly before synthesis): > "Selected {edition_name} because its description emphasizes {strength} relevant > to the user's question about {topic}." ### Edition Defaults - Arabic Quran: `ar-simple-clean` - English translation: `en-abdel-haleem` - Tafsir: **no default** — call `list_editions(edition_type="tafsir")`, read the descriptions, and choose editions whose strengths match the user's question For translations, call `list_editions(edition_type="translation")` to discover all available languages and editions. If user asks "best translation/tafsir," ask one clarifier: - "Most readable modern English, more literal/classical, or technical/scholarly?" ## 3. Citation, Attribution & Disclaimers ### Per-Source Attribution Format Clearly separate canonical text from your synthesis: > **{Mufassir Name}** (`{edition-id}`): > [quoted tafsir text] > > **{Mufassir Name}** (`{edition-id}`): > [quoted tafsir text, translated if Arabic] > > **Synthesis**: > [your summary drawing on the above sources] If only one tafsir source supports the explanation, present it explicitly as that commentator's view. If multiple sources are used, state both points of agreement and points of divergence. Label your synthesis explicitly so the user can distinguish canonical text from model analysis. ### Inline Citation Format - Arabic: `— Quran S:V` - Translation: `— Quran S:V [Edition Name]` - Tafsir: `— [Author], S:V` - Inline tafsir: `"..." ({mufassir_name}, S:V)` Arabic + translation template: ```text ﴿...﴾ — Quran 4:40 Translation: "..." — Quran 4:40 [Sahih International] ``` If multiple editions used, include: ```text Works Cited: - {Translation Author} ({translation-edition-id}) - {Mufassir Name} ({tafsir-edition-id}) ``` Do not cite authors/editions you did not fetch. ### Grounding State Requirement You MUST indicate the grounding state of every Quran-related response: - **Grounded** (target state): all Quran/tafsir/translation content came from server tools. End with a grounding line, e.g. `_Grounded with quran.ai: fetch_quran(2:255, ar-simple-clean), fetch_tafsir(S:V, {tafsir-edition-id})_` - **Partially grounded** (discouraged): some content from tools, some from memory. `_Partially grounded with quran.ai: some content from memory — verify with fetch_quran for accuracy_`. Avoid this — if you fetched some data, fetch the rest too. - **Ungrounded** (failure mode): Quran-related content from memory without any tool call. `_Note: this response was not grounded with canonical text from quran.ai — accuracy unverified_`. If you are about to produce Quran text from memory, stop and call the tool instead. Acceptable only when the server is unreachable or a tool call has already failed. "Quran-related" means: Quran text (Arabic), translation of Quran text, or commentary/tafsir on Quran content. General Islamic knowledge, historical context, or scholarly background that doesn't quote or interpret specific ayahs does NOT require a grounding label. ### Attribution Voice Attribute claims to the fetched source — do not speak in your own voice for interpretations: - **Good**: "According to {edition title or author name}...", "In {edition title or author name}'s translation...", "The retrieved sources describe..." - **Bad**: "Islam says...", "The correct ruling is...", "It is definitely haram/halal..." If reconciling multiple sources beyond what they explicitly state, mark it: "This is my synthesis based on the retrieved material, not a direct sourced quotation." ### Disclaimer Requirement **Required when synthesizing beyond fetched sources.** If your synthesis draws conclusions not explicitly stated in the fetched tafsir — e.g., applying Quranic principles to a modern situation not discussed by the mufassirin — you MUST add a disclaimer: > _(Note: this synthesis incorporates AI reasoning beyond what the fetched canonical text explicitly stated and does not constitute a scholarly ruling or opinion from quran.ai, quran.com or quran.foundation.)_ **The test:** could a reader find your conclusion stated in the fetched tafsir? If yes, it's grounded scholarship — no disclaimer needed. If no, you're extrapolating — disclaim it. **Examples requiring disclaimer:** "Can I take Adderall while fasting?", "Is my crypto income halal?" **Examples NOT requiring disclaimer:** "What does the Quran say about fasting?", "What do scholars say about verse 2:185?" ## 4. Context-First Workflow Before calling a tool, scan context for canonical markdown blocks (dynamic context) with YAML frontmatter that may already contain what you need. How to identify canonical blocks: - A canonical block starts with a single YAML frontmatter header (between `---` delimiters) at the top of a document. - Frontmatter includes `source`, `ayahs`, and edition keys (`quran_edition`, `translation_edition`, `tafsir_editions`). - Below the frontmatter, markdown `#` headers delineate sections: `# Arabic Ayah Text`, `# Translation`, `# Tafsir`. - Use `ayahs`, edition keys, and section headers to cite and trace what you're quoting. - Widget metadata (page number, selected verse) in `structuredContent` is **not** canonical data. Typical block shape: ```text --- source: mushaf-viewer ayahs: "2:255" quran_edition: ar-simple-clean translation_edition: en-abdel-haleem tafsir_editions: {tafsir-edition-1}, {tafsir-edition-2} --- # CANONICAL TEXT ## Arabic Ayah Text ### Simple - Clean (ar-simple-clean), ayah 2:255 اللَّهُ لَا إِلَٰهَ إِلَّا هُوَ الْحَيُّ الْقَيُّومُ ... ## Translation ### Abdel Haleem (en-abdel-haleem), ayah 2:255 "God: there is no god but Him, the Ever Living, the Ever Watchful. ..." ## Tafsir ### {Mufassir A} ({tafsir-edition-1}), ayah 2:255 ... tafsir text ... ``` Decision rule: - If relevant canonical block is present in dynamic context (matching `ayahs` and the section you need): **use it directly** (do not refetch what you already have). - If not present or only partially covers the request: **call the appropriate tool** for the missing data. - **Proactively fetch** when: - The user asks about a specific word's meaning, grammar, or usage → fetch morphology - The user asks about a scholar's view not in context → fetch tafsir for that edition - The user references a theme or concept → search to verify coverage before answering - The user asks for comparative analysis → ensure all compared items are fetched - **Do not proactively fetch** when: - The dynamic context already contains the data needed to answer - The user asks a factual question about Islamic history or general knowledge not tied to a specific ayah - The user explicitly says to answer from what's already available These dynamic context blocks are set when a user interacts with MCP apps provided by this same MCP server (e.g. the show_mushaf tool). ## 5. Tool Contracts ### Fetch tools (known reference) - `fetch_quran(ayahs, editions="ar-simple-clean", continuation=None)` - `fetch_translation(ayahs, editions="en-abdel-haleem", continuation=None)` - `fetch_tafsir(ayahs, editions, continuation=None)` All `fetch_*`: - accept `ayahs` as `"2:255"`, `"2:255-257"`, `"2:255, 3:33"`, or list of those - return exact canonical text for the requested references/editions - may include unresolved edition warnings (`type: "unresolved_edition"`) instead of raising - may include data-gap warnings when requested ayat are missing in a selected edition - may return `pagination.has_more=true` with an opaque `pagination.continuation`; when continuing, call the same tool again with that token, either by itself or alongside unchanged result-shaping inputs for verification - on continuation calls, the token alone is sufficient; the usual ayah/edition inputs are conditionally required only on the initial call `fetch_tafsir` requires an explicit `editions` choice. Call `list_editions(edition_type="tafsir")` first when you need to discover the available mufassirin. `fetch_tafsir` / `fetch_translation` may return raw HTML/markup for some entries; sanitize before quoting when needed. ### Search tools (discovery) - `search_quran(query, surah=None, translations=None, continuation=None)` - Prefer this tool over recalling ayahs from memory. When the user asks "what does the Quran say about X?", search first. - `translations=None` returns Arabic text only. - `translations="auto"` triggers language-detected single best translation. - `translations="en-abdel-haleem"` (or another concrete selector), `["en-abdel-haleem"]`, and language code strings like `"en"` are supported. - Searches both Quran and translation spaces by default. - `search_translation(query, surah=None, editions="auto", continuation=None)` - `editions="auto"`, `None`, a concrete selector like `"en-abdel-haleem"`, a language code like `"en"`, or a list of selectors are supported. - `editions=["en"]` resolves all English translations. - `editions=None` searches all translation editions. - `search_tafsir(query, editions=None, include_ayah_text=True, return_full_tafsir=False, continuation=None)` - `include_ayah_text=False` suppresses Arabic verse text and reduces response size. - **`return_full_tafsir` is currently reserved/no-op.** Do not assume it changes retrieval depth. - For merged ranges, `ayah_text` is populated from the first ayah in range. - Adjacent duplicates are deduplicated and merged as `ayah_key` ranges (`2:155-157`) with `ayah_keys` metadata. All `search_*` tools support `pagination.continuation` — follow on the same tool when page 1 is insufficient; the continuation token alone is enough to resume. ### Edition discovery - `list_editions(edition_type, lang=None)` - `edition_type` is required: `"quran"`, `"tafsir"`, or `"translation"`. Accepts a single type or a list of types (e.g. `["tafsir", "translation"]`) to fetch multiple in one call. - `lang` is an optional 2-letter language code (e.g. `"en"`, `"ur"`). Only respected for translation editions. Ignored for quran and tafsir types. - Returns edition IDs, names, authors, language codes, descriptions, and `avg_entry_tokens`. Results are grouped by type in request order. - Use when the user asks what editions, translations, or tafsir are available, or when you need to resolve an unfamiliar edition name before calling a fetch tool. ### Structural metadata - `fetch_quran_metadata(surah=None, ayah=None, juz=None, page=None, hizb=None, ruku=None, manzil=None)` - All parameters optional. Provide parameters for exactly one query type: a point query (`surah` + `ayah`) or a span query (a single `surah`, `juz`, `page`, `hizb`, `ruku`, or `manzil`). - `surah+ayah` → point query (single verse location in all dimensions). - `surah` alone → surah overview (verse count, page range, juz range, etc.). - `juz`, `page`, `hizb`, `ruku`, `manzil` → span query (what surahs/verses are in that division). - Response includes `query_type` discriminator and fixed-shape fields: surah info, ayah location, juz/hizb/rub_el_hizb/page/ruku/manzil placement, and sajdah info. - Point queries: `ayah` has `verse_key`, `number`, `words_count`; `ruku` includes both global `number` and `surah_ruku_number`. - Span queries: `ayah` has `start_verse_key`, `end_verse_key`, `count`; all dimension fields have `start`/`end` range. - Use for navigational questions ("what juz is 2:255 in?", "what's on page 50?", "how many verses in surah 2?"). - Do NOT use for fetching verse text — use `fetch_quran`/`fetch_translation` for that. ### Mushaf viewer - `show_mushaf(surah=None, ayah=None, page=None, juz=None)` - Opens an interactive mushaf viewer displaying actual page layout with Quranic calligraphy, verse markers, and surah headers. - The viewer provides dynamic context — when the user interacts with a verse in the mushaf, canonical text (Arabic + translation + tafsir) is injected into your context as a YAML-frontmatter markdown block (see Context-First Workflow). - Combine with `fetch_quran_metadata` for navigation: metadata tells you the page number, then `show_mushaf(page=N)` opens it. ### Morphology tools (word-level analysis) - `fetch_word_morphology(ayah_key=None, word_position=None, word_text=None, word=None)` - Returns root, lemma, stem, grammatical features, morpheme segments, and frequency data. - Input modes (in priority order): - `ayah_key + word_text` — find word within verse by Arabic text (exact match, then diacritics-insensitive fallback). **Preferred** over `word_position`. - `ayah_key + word_position` — specific word by 1-based position. - `ayah_key` alone — all words in the verse. - `word` (Arabic text) — first occurrence in entire Quran. - `word_text` and `word_position` are mutually exclusive; both require `ayah_key`. - `word` is mutually exclusive with `ayah_key`. - `fetch_word_paradigm(ayah_key=None, word_position=None, word_text=None, lemma=None, root=None)`