# MCP for developers: Choose a Shamela MCP scope: one book or all

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

> shamela_search_library names one of twelve shelves. What each contains, what they leave out, and why scoping matters even where it is optional.

`shamela_search_library` requires a scope. The raw `shamela_*` searches do not — but the reason the curated one insists is worth understanding before you decide to skip it.

## Why a scope is required

Full-text search over this library ranks results by **term statistics** — roughly, how unusual your words are and how often they appear on a page. That is a reasonable default for a search engine and a bad one for a library of religious texts, because term frequency knows nothing about scholarly authority.

Two real examples, both from searching the whole library:

- **`التيمم`** (dry ablution) returns **26,098 hits**, topped by a poetry anthology from 710 AH. Every fiqh manual that actually rules on the subject sits below it.
- **`إنما الأعمال بالنيات`** returns **6,815 hits** in which **Sahih al-Bukhari never appears at all** — buried under minor collections that merely repeat the hadith more often per page.

An assistant handed those results would cite them confidently.

`shamela_search_library` therefore will not run without a scope. `shamela_search` (`match: 'words'`) will, and there are real uses for it — but if you are asking "where is this text printed," scope the search.

The raw `shamela_*` searches take a scope _object_ (`{"book_ids": […]}` or `{"category_ids": […]}`), but they also accept one of the twelve names below as a plain string: `shamela_search` (`match: 'words'`) with `"scope": "fiqh-shafii"` runs the same shelf `shamela_search_library` would. An unknown name returns a tool error listing the valid ones. `shamela_find` (`kind: 'book'`) searches the catalogue rather than page text and has no `book_ids`, so the two book-pinned scopes (`hadith-primary`, `tafsir-canonical`) are refused there; the category scopes work.

## The twelve scopes

| Scope              | Contains                                                               | Books |
| ------------------ | ---------------------------------------------------------------------- | ----- |
| `hadith-primary`   | The eight primary collections, each pinned to a specific printing      | 8     |
| `tafsir-canonical` | Ibn Kathir, al-Tabari, Ibn al-Jawzi and three more, read in that order | 6     |
| `fiqh-hanafi`      | Hanafi fiqh, plus usul and general fiqh                                | 1,034 |
| `fiqh-maliki`      | Maliki fiqh, plus usul and general fiqh                                | 1,036 |
| `fiqh-shafii`      | Shafi'i fiqh, plus usul and general fiqh                               | 1,037 |
| `fiqh-hanbali`     | Hanbali fiqh, plus usul and general fiqh                               | 1,100 |
| `fiqh-comparative` | All four schools, plus inheritance, governance and fatwa collections   | 1,559 |
| `aqeedah`          | Creed and sects                                                        | 958   |
| `hadith-sciences`  | Hadith commentary, takhrij, and the sciences of hadith                 | 1,957 |
| `tafsir`           | The whole tafsir shelf and Quranic sciences                            | 586   |
| `seerah`           | Prophetic biography, history, and biographical dictionaries            | 972   |
| `lugha`            | Arabic language, lexicons, grammar and adab                            | 1,052 |

## The two small scopes are small on purpose

`hadith-primary` (8 books) and `tafsir-canonical` (6 books) are curated lists, not categories.

**`hadith-primary`** pins each collection to a named printing: al-Bukhari is the Sultaniyya, Muslim is the ʿAbd al-Baqi numbering, and so on. This does two jobs at once. It keeps the search focused — the full sunnah category is 1,243 books, and searching all of them surfaces minor works that merely repeat a hadith. And it makes the page number mean something: printings paginate differently, so a volume and page without a named edition is not a citation a reader can check.

**`tafsir-canonical`** exists because the underlying verse index reads books in catalogue order, which is an accident of numbering rather than a judgement. For one verse that meant a grammar-parsing work and an esoteric commentary were surfaced while Ibn Kathir and al-Tabari — both indexed for that same verse — went unread. The curated list fixes the order.

Use the broad `tafsir` scope (586 books) when you want breadth; use `tafsir-canonical` when you want the works most readers would expect to be consulted first.

## Picking one

| If you are asking about…                         | Start with                                                  |
| ------------------------------------------------ | ----------------------------------------------------------- |
| Whether a hadith exists, and where it is printed | `hadith-primary`                                            |
| What a well-known commentator said about a verse | `tafsir-canonical`                                          |
| A ruling within one school                       | `fiqh-hanafi`, `fiqh-maliki`, `fiqh-shafii`, `fiqh-hanbali` |
| How the schools differ on a question             | `fiqh-comparative`                                          |
| A grading, a chain, or how a hadith was received | `hadith-sciences`                                           |
| A point of creed                                 | `aqeedah`                                                   |
| An event, a life, or a narrator's biography      | `seerah`                                                    |
| What an Arabic word means or how it is parsed    | `lugha`                                                     |

> Scope narrows _which books_ are searched, never how the words are matched. A scope with 8 books and one with 1,957 run the same search — you get fewer, better-placed results from the small one.

## What the scopes do not cover

The twelve scopes span 26 of the catalogue's 41 categories — **7,084 of 8,594 books**. The remaining 1,510 have no scope of their own and are reachable only through the raw `shamela_*` tools:

| Not in any scope                                                 | Books |
| ---------------------------------------------------------------- | ----- |
| الأدب — literature and belles-lettres                             | 406   |
| كتب عامة — general works                                         | 357   |
| التجويد والقراءات — tajwīd and qirāʾāt                           | 152   |
| الجوامع — comprehensive collections                              | 137   |
| فهارس الكتب والأدلة — indexes and guides                          | 102   |
| البلدان والرحلات — geography and travel                           | 97    |
| العلل والسؤلات الحديثية — hadith defects and questions            | 78    |
| الأنساب — genealogy                                               | 52    |
| البلاغة — rhetoric                                                | 44    |
| Six smaller categories (poetry, medicine, logic, prosody, other) | 85    |

If your question lands on one of those shelves — a qirāʾāt ruling, a narrator's genealogy, a point of ʿilal — `shamela_search_library` will come back empty even though the books are there. Use `shamela_search` (`match: 'words'`) with an explicit `category_ids` scope instead, which you can look up with `shamela_find` (`kind: 'category'`).

If a scope returns nothing, that is information rather than a dead end. Try the broader neighbour — `tafsir-canonical` → `tafsir`, or one school → `fiqh-comparative` — and note that the narrower shelf was silent.

## Next steps

- [Open Quran Gallery MCP](https://qurangallery.com/mcp)
- [Hosted MCP server or your own RAG or OpenITI corpus?](https://qurangallery.com/docs/mcp/vs-own-rag-and-openiti)
- [Why scope matters: one search on one shelf and on all](https://qurangallery.com/docs/mcp/why-scope-matters)
- [MCP server for Islamic texts: what it does](https://qurangallery.com/docs/mcp/overview)
