# MCP for developers: MCP tools for classical Arabic books: the full list

Source: https://qurangallery.com/docs/mcp/tools

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

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

| Tool                                       | Use it when                                                                                                                                                                                                   |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shamela_search_library`                   | **The default.** Scoped search with citations and match reporting. See [its reference](https://qurangallery.com/docs/mcp/search-library).                                                                                                     |
| `search`                                   | **Quick 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_topic`                     | Before 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.

| Tool     | Input                       | Returns                                                                                                                             |
| -------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `search` | `query` (Arabic)            | `results`: up to 10 of `{ id, title, url }`. `id` is `bookId:pageId`; `url` is the page in the Maktabah reader.                     |
| `fetch`  | `id` 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

| Tool                                | Use 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

| Tool                                    | Use it when                                                                                                                                                                             |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shamela_cite` (`mode: 'printed_page'`) | **Verifying a citation.** Turn «vol. 4, p. 405» into the page ids that carry it.                                                                                                        |
| `shamela_verify_quote`                  | **Checking 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](https://qurangallery.com/docs/mcp/verify-a-quotation). |
| `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

| Tool                                            | Use 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

| Tool                                         | Use 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

| Tool                                     | Use 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_brief`                      | The 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.

| Prompt           | Arguments       | What it does                                                                                                         |
| ---------------- | --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `takhrij_hadith` | `text`          | Locates a hadith across the collections with its isnād, and never grades it. See [Hadith takhrij](https://qurangallery.com/docs/mcp/hadith-takhrij). |
| `cite_passage`   | `text`          | Finds a passage and cites it with edition, volume and page.                                                          |
| `compare_tafsir` | `surah`, `ayah` | Compares 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](https://qurangallery.com/docs/mcp/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 name                       | Now                                                                 |
| ------------------------------ | ------------------------------------------------------------------- |
| `shamela_books_by_period`      | `shamela_find` (`kind: 'period'`)                                   |
| `shamela_brief`                | `shamela_get_brief`                                                 |
| `shamela_get_author`           | `shamela_get_details` (`kind: 'author'`)                            |
| `shamela_get_aya`              | `shamela_lookup_quran` (`mode: 'aya'`)                              |
| `shamela_get_book`             | `shamela_get_details` (`kind: 'book'`)                              |
| `shamela_get_book_parts`       | `shamela_read` (`unit: 'parts'`)                                    |
| `shamela_get_book_section`     | `shamela_read` (`unit: 'section'`)                                  |
| `shamela_get_books_for_hadith` | `shamela_lookup_hadith` (`mode: 'sources'`)                         |
| `shamela_get_citation`         | `shamela_cite` (`mode: 'citation'`)                                 |
| `shamela_get_isnad`            | `shamela_lookup_rijal` (`mode: 'isnad'`)                            |
| `shamela_get_narrator`         | `shamela_lookup_rijal` (`mode: 'narrator'`)                         |
| `shamela_get_page`             | `shamela_read` (`unit: 'page'`)                                     |
| `shamela_get_page_services`    | `shamela_read` (`unit: 'services'`)                                 |
| `shamela_get_pages_range`      | `shamela_read` (`unit: 'range'`)                                    |
| `shamela_get_tafseer_of_aya`   | `shamela_lookup_tafsir` (`mode: 'coverage'`)                        |
| `shamela_get_tafseer_texts`    | `shamela_lookup_tafsir` (`mode: 'texts'`)                           |
| `shamela_get_toc`              | `shamela_read` (`unit: 'toc'`)                                      |
| `shamela_guide`                | `shamela_get_guide`                                                 |
| `shamela_health`               | `shamela_check_health`                                              |
| `shamela_list_books_by_period` | `shamela_find` (`kind: 'period'`)                                   |
| `shamela_list_categories`      | `shamela_find` (`kind: 'category'`)                                 |
| `shamela_list_tafsirs_for_aya` | `shamela_lookup_tafsir` (`mode: 'coverage'`)                        |
| `shamela_recon`                | `shamela_survey_topic` (`root` → `term`)                            |
| `shamela_resolve`              | `shamela_find` (`kind: 'name'`)                                     |
| `shamela_resolve_name`         | `shamela_find` (`kind: 'name'`)                                     |
| `shamela_resolve_printed_page` | `shamela_cite` (`mode: 'printed_page'`)                             |
| `shamela_resolve_work`         | `shamela_find` (`kind: 'work'`)                                     |
| `shamela_root_stats`           | `shamela_survey_topic` (`mode: 'morphological'`) (`root` → `term`)  |
| `shamela_search_authors`       | `shamela_find` (`kind: 'author'`)                                   |
| `shamela_search_batch`         | `shamela_search` (`match: 'batch'`) (`probes` → `queries`)          |
| `shamela_search_books`         | `shamela_find` (`kind: 'book'`)                                     |
| `shamela_search_boolean`       | `shamela_search` (`match: 'boolean'`)                               |
| `shamela_search_exact`         | `shamela_search` (`match: 'exact'`)                                 |
| `shamela_search_hadith`        | `shamela_lookup_hadith` (`mode: 'search'`)                          |
| `shamela_search_isnad`         | `shamela_lookup_rijal` (`mode: 'isnad_search'`)                     |
| `shamela_search_narrators`     | `shamela_lookup_rijal` (`mode: 'narrators'`)                        |
| `shamela_search_pages`         | `shamela_search` (`match: 'words'`)                                 |
| `shamela_search_phrase`        | `shamela_search` (`match: 'phrase'` or `'near'`) (`mode` → `match`) |
| `shamela_search_quran`         | `shamela_lookup_quran` (`mode: 'search'`)                           |
| `shamela_search_titles`        | `shamela_find` (`kind: 'heading'`)                                  |

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

## Next steps

- [Open Quran Gallery MCP](https://qurangallery.com/mcp)
- [shamela_search_library: search Arabic books with citations](https://qurangallery.com/docs/mcp/search-library)
- [Use the Shamela MCP server from Python, LangChain and agents](https://qurangallery.com/docs/mcp/use-with-langchain-and-agents)
- [MCP server for Islamic texts: what it does](https://qurangallery.com/docs/mcp/overview)
