Skip to content

MCP tools for classical Arabic books: the full list

The 15 read-only tools of the Quran Gallery MCP server, plus 3 prompts and a resource: search, reading, citations, isnad, narrators, tafsir, catalogue.

On this page

Fifteen tools, the same for every client, all read-only. Four are ours (shamela_search_library, search, fetch, shamela_verify_quote); eleven come from the library server itself. Nine of those eleven are routers: each takes one mode argument (match, kind, unit or mode) that selects what it does, and the tables below list every mode on its own row. search and fetch are the standard pair ChatGPT deep research requires, and every client sees them. Alongside the tools the server offers three prompts and one resource.

Your client lists them for you. This page is a map, so you know what exists and which one to reach for — every tool carries its own parameter documentation in the schema your client already received.

Start with shamela_search_library. It requires a scope and reports how it matched, which is the right default for “find me this text.” Reach for the raw shamela_* tools when you need something it cannot do. All queries must be in Arabic.

Searching

ToolUse it when
shamela_search_libraryThe default. Scoped search with citations and match reporting. See its reference.
searchQuick generic entry; the pair ChatGPT deep research needs. One query across the whole library; returns results of id, title, url. Details below.
shamela_search (match: 'words')You want the raw page search, including unscoped. Ranks by term frequency — read the warning below.
shamela_search (match: 'phrase')You need an exact consecutive phrase, or proximity matching.
shamela_search (match: 'exact')Diacritics (التشكيل) and hamza/alef forms must match exactly.
shamela_search (match: 'boolean')You need OR and NOT, not just AND.
shamela_find (kind: 'heading')You are looking for a chapter or section heading, not body text.
shamela_lookup_hadith (mode: 'search')You have a hadith’s wording and want the collections carrying it.
shamela_search (match: 'batch')Up to 24 scoped searches in one call, merged and deduplicated.
shamela_survey_topicBefore searching: how much does the library hold on a term, and on which shelves, centuries, books and authors? Counts the word as written by default; mode: 'morphological' counts every form of its root.

shamela_search (match: 'words') will run unscoped, and usually should not. Ranking is by term frequency, which knows nothing about scholarly authority. Unscoped, التيمم returns 26,098 hits topped by a 710 AH poetry anthology, and إنما الأعمال بالنيات returns 6,815 hits in which Sahih al-Bukhari never appears. Pass a scope, or use shamela_search_library.

search and fetch

ChatGPT deep research and company knowledge expect two tools with fixed shapes. They are listed to every client, as the standard pair. Both are a quick, generic entry: one argument, unscoped. For hadith, tafsir or fiqh prefer shamela_search_library, and use shamela_search for a scope, an exact phrase or paging.

ToolInputReturns
searchquery (Arabic)results: up to 10 of { id, title, url }. id is bookId:pageId; url is the page in the Maktabah reader.
fetchid from a search result{ id, title, text, url, metadata }. The text keeps the main text and the footnote apart, with the footnote under its own label.

Both return structured content and the same JSON as text. search is unscoped, so it ranks like shamela_search (match: 'words'); prefer shamela_search_library when your client does not need this shape.

Reading

ToolUse it when
shamela_read (unit: 'page')You have a book_id + page_id and want the full page — body, footnotes, and all.
shamela_read (unit: 'range')You need up to 20 consecutive pages.
shamela_read (unit: 'section')You want every page under one chapter heading.
shamela_read (unit: 'toc')The table of contents of a book.
shamela_read (unit: 'parts')The volumes of a multi-volume work.
shamela_read (unit: 'services')Which verses, hadith keys and isnād markers a page carries.

Citations

ToolUse it when
shamela_cite (mode: 'printed_page')Verifying a citation. Turn «vol. 4, p. 405» into the page ids that carry it.
shamela_verify_quoteChecking a quotation. Does this Arabic wording occur in the library, and where: book, printed page, main text or footnote. See Verify an AI-quoted passage.
shamela_find (kind: 'work')Resolve a cited title (and author, and edition) to a catalogue entry — or refuse.
shamela_cite (mode: 'citation')Format a citation in one of three styles.
shamela_find (kind: 'name')Disambiguate an Arabic name fragment to book or author ids.

Those first two are the reason this surface is worth having. A claim like “al-Mughni, 4/405” can be checked rather than believed: resolve the work, resolve the page, read it.

Isnād and narrators

ToolUse it when
shamela_lookup_rijal (mode: 'narrators')Find a narrator by name — 18,989 of them, death years 2–774 AH.
shamela_lookup_rijal (mode: 'narrator')The full dossier: lineage, death year, ṭabaqa, gradings.
shamela_lookup_rijal (mode: 'isnad_search')Search 45,220 indexed chains across ten hadith books.
shamela_lookup_rijal (mode: 'isnad')The chain(s) printed on one page, with narrator names resolved.
shamela_lookup_hadith (mode: 'sources')Every collection recording the same hadith, by its shared key.

Qur’an and tafsir

ToolUse it when
shamela_lookup_quran (mode: 'search')Search the 6,236 verses (Hafs from Asim).
shamela_lookup_quran (mode: 'aya')Fetch verses by number, or by surah + ayah.
shamela_lookup_tafsir (mode: 'coverage')Which tafsir books comment on this verse, with the page of each, and an honest status for the books the index does not cover. downloaded_only: false adds books whose text is not on the server.
shamela_lookup_tafsir (mode: 'texts')The actual commentary texts for one verse, across sources, in one call.

Catalogue

ToolUse it when
shamela_find (kind: 'book')Find books by name, author, or bibliographic description.
shamela_find (kind: 'author')Find authors by name or biography.
shamela_get_details (kind: 'book')Full metadata for one book.
shamela_get_details (kind: 'author')Full metadata for one author, optionally with their books.
shamela_find (kind: 'category')All 41 categories with book counts.
shamela_find (kind: 'period')Filter the catalogue by period, AND-combining constraints.
shamela_get_briefThe library server’s own operating brief for programmatic callers.

Prompts

Ready-made prompts your client may list. Each is English text that tells the model to answer in your language.

PromptArgumentsWhat it does
takhrij_hadithtextLocates a hadith across the collections with its isnād, and never grades it. See Hadith takhrij.
cite_passagetextFinds a passage and cites it with edition, volume and page.
compare_tafsirsurah, ayahCompares what the available tafsir books say on one verse.

Resource

qurangallery://grounding-rules is a text/markdown resource holding the citation contract. See Grounding rules.

What is not exposed

Three of the library server’s tools are withheld, and not because they are powerful. They report on the machine the server runs on, so a remote caller would be reading facts about our infrastructure while believing they were reading facts about a library:

  • shamela_list_downloaded_books — what is downloaded on the host. Use shamela_find (kind: 'book'), which reads the catalogue, or shamela_get_details (kind: 'book'), which says whether a book’s text is on the server.
  • shamela_check_health — server version and internal diagnostics.
  • shamela_get_guide — the user guide for the Shamela desktop extension, describing an interface you do not have.

Nothing about the corpus is withheld.

Old tool names

Library server 1.4.0 folded 39 tools into nine routers. The old names still work, unlisted, and the result carries _meta.deprecated_alias naming the new tool. They are removed only after they have had no calls for 14 days. The old name maps to the new tool and the mode value to send:

Old nameNow
shamela_books_by_periodshamela_find (kind: 'period')
shamela_briefshamela_get_brief
shamela_get_authorshamela_get_details (kind: 'author')
shamela_get_ayashamela_lookup_quran (mode: 'aya')
shamela_get_bookshamela_get_details (kind: 'book')
shamela_get_book_partsshamela_read (unit: 'parts')
shamela_get_book_sectionshamela_read (unit: 'section')
shamela_get_books_for_hadithshamela_lookup_hadith (mode: 'sources')
shamela_get_citationshamela_cite (mode: 'citation')
shamela_get_isnadshamela_lookup_rijal (mode: 'isnad')
shamela_get_narratorshamela_lookup_rijal (mode: 'narrator')
shamela_get_pageshamela_read (unit: 'page')
shamela_get_page_servicesshamela_read (unit: 'services')
shamela_get_pages_rangeshamela_read (unit: 'range')
shamela_get_tafseer_of_ayashamela_lookup_tafsir (mode: 'coverage')
shamela_get_tafseer_textsshamela_lookup_tafsir (mode: 'texts')
shamela_get_tocshamela_read (unit: 'toc')
shamela_guideshamela_get_guide
shamela_healthshamela_check_health
shamela_list_books_by_periodshamela_find (kind: 'period')
shamela_list_categoriesshamela_find (kind: 'category')
shamela_list_tafsirs_for_ayashamela_lookup_tafsir (mode: 'coverage')
shamela_reconshamela_survey_topic (root → term)
shamela_resolveshamela_find (kind: 'name')
shamela_resolve_nameshamela_find (kind: 'name')
shamela_resolve_printed_pageshamela_cite (mode: 'printed_page')
shamela_resolve_workshamela_find (kind: 'work')
shamela_root_statsshamela_survey_topic (mode: 'morphological') (root → term)
shamela_search_authorsshamela_find (kind: 'author')
shamela_search_batchshamela_search (match: 'batch') (probes → queries)
shamela_search_booksshamela_find (kind: 'book')
shamela_search_booleanshamela_search (match: 'boolean')
shamela_search_exactshamela_search (match: 'exact')
shamela_search_hadithshamela_lookup_hadith (mode: 'search')
shamela_search_isnadshamela_lookup_rijal (mode: 'isnad_search')
shamela_search_narratorsshamela_lookup_rijal (mode: 'narrators')
shamela_search_pagesshamela_search (match: 'words')
shamela_search_phraseshamela_search (match: 'phrase' or 'near') (mode → match)
shamela_search_quranshamela_lookup_quran (mode: 'search')
shamela_search_titlesshamela_find (kind: 'heading')

Prefer the new names, and send the mode argument shown in the second column.

Next steps

Questions

How many tools does the Quran Gallery MCP server have?

15 read-only tools, the same for every client. Four are ours and 11 come from the library server itself.

Which tool should I call first?

shamela_search_library. It requires a scope and reports how it matched, which suits most find-me-this-text questions.

What are search and fetch for?

They are the standard pair ChatGPT deep research expects: search takes one Arabic query across the whole library and fetch reads a result by id.

What does it mean that a tool is a router?

One tool name covers several operations, and a mode argument such as match, kind, unit or mode picks which one runs.

Does the server offer prompts or resources?

Yes: three prompts, takhrij_hadith, cite_passage and compare_tafsir, and one resource, qurangallery://grounding-rules.

How do I read a full page or check a quotation?

Use shamela_read with unit set to page to read a page, and shamela_verify_quote to check whether an Arabic quotation occurs in the library.

Edit this page on GitHub