quran-usage-guide

name	quran-usage-guide
description	Use when the user asks to quote an ayah/surah, translate a verse, explain meaning/context/tafsir, find verses about a theme, compare translations/tafsir, analyze Arabic word patterns, or view a mushaf page. Also use for any question the Qur'an might address, any Islamic question that might have an answer from tafsir or scholarly commentary, or anything where canonical scripture or insights from tafsir could ground or add value to the response.
metadata	{"mcp-server":"quran.ai MCP"}

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 a scholarly interpretive claim (what a verse "means" according to mufassirin, what scholars say it "implies", "teaches", or "refers to"), you MUST ground it in tafsir text that you fetched (fetch_tafsir) or already present in context.

If you have not fetched tafsir and the user is asking for scholarly interpretation, restrict yourself to:

• Quoting the Arabic and/or translation (canonical text)
• Simple restatement of the translation text only (no added interpretive inference)

Exception — Contemplative reflection (tadabbur): Observations about linguistic patterns, morphological features, structural elements, or connections to contemporary knowledge are permitted — provided: (1) the canonical Quranic text has already been fetched, (2) linguistic claims are verified by actual morphology tool calls (not memory), (3) the observation is clearly labeled as reflection using the Applied Reasoning Disclaimer, and (4) no fabricated text, citations, or scholarly consensus is presented. Fetching relevant tafsir first is strongly encouraged — reflection that builds on scholarly tradition is richer than reflection on the raw text alone. See GROUNDING_RULES.md "Engagement Modes" for full standards.

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:

﴿...﴾
— Quran 4:40

Translation: "..."
— Quran 4:40 [Sahih International]

If multiple editions used, include:

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 — whether applying Quranic principles to a modern situation, offering contemplative reflection, or cross-source synthesis — you MUST add a label:

(Note: this [synthesis / reflection / applied reasoning] incorporates reasoning beyond the fetched canonical text 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:

---
source: mushaf-app
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, continuation=None)

  • include_ayah_text=False suppresses Arabic verse text and reduces response size.
  • 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 app

• show_mushaf(surah=None, ayah=None, page=None, juz=None)
  • Opens an interactive mushaf app displaying actual page layout with Quranic calligraphy, verse markers, and surah headers.
  • The app 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.