fetch_grounding_rules
ChatGPTReturns 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_mushaf
ChatGPTFetch mushaf page rendering data for a specific page number. Used by the mushaf app UI for page navigation. Returns word layout, verse metadata, and surah headers. Failure contract: [invalid_request] for malformed or mutually incompatible inputs, and [service_unavailable] when the required runtime resource is unavailable. POSTREQUISITE: 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.
fetch_quran
ChatGPTPREREQUISITE: 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_metadata
ChatGPTFetch 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_skill_guide
ChatGPTReturn 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_tafsir
ChatGPTPREREQUISITE: 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_translation
ChatGPTPREREQUISITE: 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_word_concordance
ChatGPTFind 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_morphology
ChatGPTFetch 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_paradigm
ChatGPTFetch 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.
list_editions
ChatGPTList 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.
search_quran
ChatGPTPREREQUISITE: 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. Semantic search over Quran text. Returns ranked ayat matching the query with Arabic text and optional translations. Use the translations parameter ('auto' or specific editions) to include translated text in results, which covers most use cases that search_translation would handle. For exact verse lookup by reference (e.g., '2:255'), use fetch_quran instead. Failure contract: [invalid_request] for malformed inputs, [continuation_invalid|tampered|expired|conflict|exhausted|legacy] for bad continuation tokens, [search_backend_failure] for retrieval failures, and [search_enrichment_failure] for post-retrieval enrichment failures.
search_tafsir
ChatGPTPREREQUISITE: 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. Semantic search over tafsir (Quranic commentary) content. Returns ranked tafsir passages matching the query with citations. Especially valuable for thematic/conceptual discourse, revelation context (asbab al-nuzul), and keyword-in-commentary searches where the ayah reference isn't known upfront. Use this tool to find tafsir discussing a particular topic or concept without knowing which ayat are relevant. For fetching tafsir of a known ayah, use fetch_tafsir instead. Failure contract: [invalid_request] for malformed inputs, [continuation_invalid|tampered|expired|conflict|exhausted|legacy] for bad continuation tokens, [search_backend_failure] for retrieval failures, and [search_enrichment_failure] for post-retrieval enrichment failures.
search_translation
ChatGPTPREREQUISITE: 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. Use this tool only when you need to filter by specific translation edition(s). Semantic search over Quran translation text. Returns ranked translation passages matching the query with edition metadata. For exact verse translation lookup by reference (e.g., '2:255'), use fetch_translation instead. Prefer search_quran with translations='auto' for most use cases — it searches semantically across both Arabic and translation text, independent of any particular translator's rendering. Failure contract: [invalid_request] for malformed inputs, [continuation_invalid|tampered|expired|conflict|exhausted|legacy] for bad continuation tokens, [search_backend_failure] for retrieval failures, and [search_enrichment_failure] for post-retrieval enrichment failures.
show_mushaf
ChatGPTOpen the Quran mushaf (traditional page/book reading view) to a specific location. Renders a full-page mushaf view with Arabic calligraphy, verse markers, and surah headers. Entry points: page number, surah[+ayah], or juz. If no parameters are given, opens page 1 (Al-Fatiha). Parameters are mutually exclusive — use only one entry point. Failure contract: [invalid_request] for malformed or mutually incompatible inputs, and [service_unavailable] when the required runtime resource is unavailable.
