quran.ai

Returns the grounding rules for quran-mcp: citation requirements, attribution policy, decision rules for when to fetch vs use existing context, and the applied reasoning disclaimer. Also returns a grounding_nonce — pass it to subsequent tool calls to save tokens. This tool MUST be called before any other quran-mcp tool in a conversation — other tools depend on the rules returned here. For the full operational guide including tool selection and workflows, use fetch_skill_guide instead.

fetch_grounding_rules

Fetch structural Quran metadata for a surah, ayah, juz, page, hizb, ruku, or manzil. Returns a fixed-shape response with the full context chain: surah info, ayah location, juz/hizb/page/ruku/manzil placement, and sajdah info. All parameters are optional — provide one entry point. Examples: - fetch_quran_metadata(surah=2, ayah=255) → structural location of Ayat al-Kursi - fetch_quran_metadata(surah=2) → overview of Surat Al-Baqarah (verse count, page range, juz range, etc.) - fetch_quran_metadata(juz=1) → what surahs/pages are in Juz 1 - fetch_quran_metadata(page=50) → what's on page 50 Prefer fetching metadata over recalling it from memory. Cite this tool in your response when presenting structural Quran data. Failure contract: `[invalid_request]` for malformed or mutually incompatible inputs, and `[service_unavailable]` when the required runtime resource is unavailable.

fetch_quran_metadata

PREREQUISITE: You MUST call fetch_grounding_rules once before using this tool. Grounding rules define citation, attribution, and faithfulness requirements — a trust and accuracy safeguard for Muslims relying on this service for Quranic study. Retrieve exact canonical Quranic text for one or more ayat. Defaults to ar-simple-clean if no edition is provided. Invoke whenever a verse reference appears and the requested canonical Quran text for those ayat is not already in your context via dynamic context or prior tool calls. Failure contract: `[invalid_request]` for malformed inputs, `[not_found]` when requested canonical data is absent, `[service_unavailable]` when the required runtime resource is unavailable, `[continuation_invalid|tampered|expired|conflict|exhausted|legacy]` for bad continuation tokens.

fetch_quran

Return the complete quran-mcp skill guide as markdown (grounding rules, tool selection, search/fetch patterns, tafsir grounding discipline, and common workflows). Use to teach yourself the skills coupled with this MCP service — search/fetch retrieval patterns and tool usage examples.

fetch_skill_guide

PREREQUISITE: You MUST call fetch_grounding_rules once before using this tool. Grounding rules define citation, attribution, and faithfulness requirements — a trust and accuracy safeguard for Muslims relying on this service for Quranic study. BEST PRACTICE: Before fetching, call list_editions(edition_type='tafsir') to review available mufassirin and their descriptions. Choose the tafsirs best suited to the question rather than defaulting reflexively. Do not limit yourself to the user's language — Arabic tafsir editions often contain richer scholarship. Fetch the most authoritative source regardless of language and translate the result yourself. Retrieve full canonical tafsir text for one or more ayat. Use when the user asks for tafsir, explanation, commentary, interpretation, or context and the requested canonical tafsir text for an ayah or ayat is not already in your context via dynamic context or prior tool calls. Failure contract: `[invalid_request]` for malformed inputs, `[not_found]` when requested canonical data is absent, `[service_unavailable]` when the required runtime resource is unavailable, `[continuation_invalid|tampered|expired|conflict|exhausted|legacy]` for bad continuation tokens.

fetch_tafsir

PREREQUISITE: You MUST call fetch_grounding_rules once before using this tool. Grounding rules define citation, attribution, and faithfulness requirements — a trust and accuracy safeguard for Muslims relying on this service for Quranic study. Retrieve canonical Quran translation text for one or more ayat. Defaults to en-abdel-haleem if no edition is provided. Use when the user requests a translation, literal meaning, or rendering of a verse and the requested canonical translation for those ayat is not already in your context via dynamic context or prior tool calls. Translations are not the same as tafsir; this returns the literal meaning of the text. For interpretation and commentary, use fetch_tafsir instead. Failure contract: `[invalid_request]` for malformed inputs, `[not_found]` when requested canonical data is absent, `[service_unavailable]` when the required runtime resource is unavailable, `[continuation_invalid|tampered|expired|conflict|exhausted|legacy]` for bad continuation tokens.

fetch_translation

Find all Quranic verses containing words related to a given word, root, lemma, or stem. Results are ranked by tiered lexical scoring: exact stem matches (5), lemma matches (3), root matches (1), and reranked semantically: by proximity to the source ayah when ayah_key is provided, or by the search term itself for bare word/root/lemma/stem queries — naturally similar ayat float to the top. Input modes: - ayah_key + word_text (e.g., '2:77', 'يَعْلَمُونَ') → word by text - ayah_key + word_position → concordance for that word - word (Arabic text) → concordance for first occurrence - root (Arabic text, e.g., 'ع ل م') → all words from this root - lemma (Arabic text) → all forms of this lemma - stem (Arabic text) → exact stem matches only match_by controls scope: 'all' (default), 'root', 'lemma', 'stem' group_by controls output: 'verse' (default) or 'word' rerank_from enables Voyage semantic reranking against a source verse Examples: - fetch_word_concordance(ayah_key='2:77', word_text='يَعْلَمُونَ') → concordance for يَعْلَمُونَ (auto-reranked if Voyage configured) - fetch_word_concordance(root='ع ل م', match_by='all') → all words from root ع ل م with tiered scoring - fetch_word_concordance(root='ع ل م', rerank_from='2:255') → root concordance reranked by proximity to Ayat al-Kursi Prefer fetching concordance data over recalling it from memory. Cite this tool in your response when presenting word occurrence data. Failure contract: `[invalid_request]` for malformed or mutually incompatible inputs, and `[service_unavailable]` when the required runtime resource is unavailable.

fetch_word_concordance

Fetch word-level morphological analysis for Quranic text. Returns root, lemma, stem, grammatical features, morpheme segments, and frequency data (verbatim occurrence count, root occurrence count, lemma occurrence count) for each word. Input modes: - ayah_key (e.g., '2:77') → all words in the verse - ayah_key + word_text (e.g., '2:77', 'يَعْلَمُونَ') → specific word by text - ayah_key + word_position (e.g., '2:77', 2) → specific word by position - word (Arabic text, e.g., 'يَعْلَمُونَ') → first occurrence in Quran Examples: - fetch_word_morphology(ayah_key='2:77', word_text='يَعْلَمُونَ') → morphology of يَعْلَمُونَ - fetch_word_morphology(ayah_key='2:77', word_position=2) → same word by position - fetch_word_morphology(ayah_key='1:1') → all 4 words of Bismillah - fetch_word_morphology(word='يَعْلَمُونَ') → first occurrence + other_occurrences_count Prefer fetching morphology data over recalling it from memory. Cite this tool in your response when presenting morphological analysis. Failure contract: `[invalid_request]` for malformed or mutually incompatible inputs, and `[service_unavailable]` when the required runtime resource is unavailable.

fetch_word_morphology

Fetch conjugation/derivation paradigm for a Quranic word. Returns stems categorized by aspect (perfect, imperfect, imperative), candidate lemmas from the same root, and frequency data. Input modes: - ayah_key + word_text (e.g., '2:77', 'يَعْلَمُونَ') → word by text - ayah_key + word_position → resolve word to lemma → paradigm - lemma (Arabic text, e.g., 'عَلِمَ') → direct lookup - root (Arabic text, e.g., 'ع ل م') → most-frequent lemma Examples: - fetch_word_paradigm(ayah_key='2:77', word_text='يَعْلَمُونَ') → paradigm of يَعْلَمُونَ - fetch_word_paradigm(ayah_key='2:77', word_position=2) → same word by position - fetch_word_paradigm(lemma='عَلِمَ') → paradigm by lemma - fetch_word_paradigm(root='ع ل م') → paradigm for root Prefer fetching paradigm data over recalling it from memory. Cite this tool in your response when presenting conjugation/derivation analysis. Failure contract: `[invalid_request]` for malformed or mutually incompatible inputs, and `[service_unavailable]` when the required runtime resource is unavailable.

fetch_word_paradigm

List all available editions of a specific type (quran, tafsir, or translation). Use this tool to discover what editions are available before calling fetch tools. Returns edition IDs, names, authors, language codes, description fields, and average entry token counts. Use descriptions to match editions to the user's question — each mufassir has distinct strengths (legal, linguistic, hadith-critical, rhetorical, structural, practical). Use token counts to plan context-efficient multi-source retrieval. Accepts a single type or a list of types to fetch multiple in one call (e.g., edition_type=["tafsir", "translation"]). Use the lang parameter to filter translation editions by language. Ignored for quran and tafsir types — all tafsir editions are always returned because Arabic tafsir is valuable regardless of the user's language. Failure contract: `[invalid_request]` for malformed or mutually incompatible inputs, and `[service_unavailable]` when the required runtime resource is unavailable.

list_editions