# MCP for developers: shamela_search_library: search Arabic books with citations

Source: https://qurangallery.com/docs/mcp/search-library

> Parameters and result fields of shamela_search_library, the MCP tool that returns verbatim Arabic passages with edition, page and a Maktabah link.

Three parameters. It searches a named slice of the library and returns passages with their citations attached.

This is one of 15 tools, and the one to try first — it is the only search that refuses to run unscoped and that tells you how it matched. For everything it cannot do, see [the full tool surface](https://qurangallery.com/docs/mcp/tools).

## Parameters

| Parameter | Required | Type    | Notes                                                                                       |
| --------- | -------- | ------- | ------------------------------------------------------------------------------------------- |
| `query`   | yes      | string  | **Arabic text only.** A quoted wording works best; a topic also works.                      |
| `scope`   | **yes**  | string  | One of twelve names — see [Choosing a scope](https://qurangallery.com/docs/mcp/scopes). This tool will not run without one. |
| `limit`   | no       | integer | Passages to return, 1–10. Defaults to 5.                                                    |

`scope` being required is the single most important thing about this tool, and the [scopes page](https://qurangallery.com/docs/mcp/scopes) explains why in full: unscoped, this library ranks by how often a word appears, which buries the books you actually want.

### The query must be in Arabic

The library is Arabic and so is the index. A query with no Arabic words is **rejected outright** — it is a tool error (`isError`), not an empty result, and the message tells the model what to do:

> _The library is Arabic, so the query must contain Arabic words. Translate the search terms into Arabic and call again, for example «إنما الأعمال بالنيات» for "actions are judged by intentions"._

That applies to English (`prayer intention`) and to transliteration (`innama al-a'mal bil-niyyat`) alike. If your assistant is working from an English question, it has to translate the search terms into Arabic before calling this tool. Nothing translates them for it. The unscoped `search` tool behaves the same way.

**Diacritics do not matter.** `انما الاعمال بالنيات` and `إِنَّمَا الْأَعْمَالُ بِالنِّيَّاتِ` return the same results, so there is no need to vowel a query or strip vowels from one you copied.

## What comes back

A result object with the passages and some context about the search itself. The shape is published as the tool's `outputSchema` in `tools/list`, so a client can read it without this page:

| Field             | Meaning                                                                                                   |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| `passages`        | The hits, described below.                                                                                |
| `relaxedToTokens` | `true` when the exact phrase was not found and a looser word search answered instead.                     |
| `scope`           | The scope that was searched, echoed back.                                                                 |
| `booksSearched`   | How many books were in that scope.                                                                        |
| `totalMatches`    | How many pages matched in total, of which you received up to `limit`. Can be `null` on the fallback pass. |
| `note`            | Present only when the result needs a caveat — see below.                                                  |

Each entry in `passages`:

| Field                            | Meaning                                                                                                                                        |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `book`                           | Title **including the printing**, e.g. `صحيح البخاري - ط السلطانية`.                                                                           |
| `author`                         | The author's name.                                                                                                                             |
| `authorDied`                     | Year of death in AH, or `null` if unknown.                                                                                                     |
| `printedPage`                    | Volume and page as that printing paginates it, e.g. `1/ 6`.                                                                                    |
| `arabic`                         | The passage itself, verbatim, with all markup removed.                                                                                         |
| `matchedIn`                      | `body`, `footnote`, `both`, or `unknown` — where the words were found.                                                                         |
| `matchQuality`                   | How the match was made, e.g. `exact_phrase`.                                                                                                   |
| `bookId`, `pageId`               | The page's Shamela identifiers.                                                                                                                |
| `edition`, `editor`, `publisher` | Bibliographic data for that printing. **Present only when the library has them**; never guessed.                                               |
| `sourceUrl`                      | `https://qurangallery.com/maktabah/book/{bookId}/{pageId}`, the same page in the Maktabah reader. Credit al-Maktaba al-Shamela when you quote. |

## The two passes

Search runs the strict pass first, then falls back:

1. **Exact phrase.** Your words, in order, as written.
2. **Words together**, if the phrase found nothing — the same words anywhere on a page, in any order.

You are always told which one answered, via `relaxedToTokens`. That flag is not bookkeeping; it changes what the result means, and [Reading a result](https://qurangallery.com/docs/mcp/reading-results) covers how.

The fallback exists because transmitted wording varies between printings. Searching `إنما الأعمال بالنيات` as a strict phrase finds one book and misses Sahih al-Bukhari, which prints `بالنية`. The looser pass finds al-Bukhari, Ibn Majah, Abu Dawud and al-Nasa'i. Running only the strict pass would turn a famous, well-attested hadith into a "not found" — which in this subject is its own kind of false claim.

## A worked example

Searching `إنما الأعمال بالنيات` in the `hadith-primary` scope returns, among others:

| Field          | Value                                                                           |
| -------------- | ------------------------------------------------------------------------------- |
| `book`         | صحيح البخاري - ط السلطانية                                                      |
| `author`       | البخاري                                                                         |
| `authorDied`   | 256                                                                             |
| `printedPage`  | `1/ 6`                                                                          |
| `matchedIn`    | `body`                                                                          |
| `matchQuality` | `exact_phrase`                                                                  |
| `arabic`       | …عُمَرَ بْنَ الْخَطَّابِ ﵁ عَلَى الْمِنْبَرِ، قَالَ: سَمِعْتُ رَسُولَ اللهِ ﷺ، يَقُولُ: «إِنَّمَا الْأَعْمَالُ بِالنِّيَّاتِ… |

With `booksSearched: 8` and `relaxedToTokens: false` — eight edition-pinned collections, and the exact phrase was found.

The leading `…` is deliberate: it marks a passage that begins mid-sentence, because the excerpt is a window onto the page rather than the whole page.

## Excerpt length

Passages are capped at roughly 1,600 Arabic characters and truncated with a trailing `…` if longer. This tool returns quotations, not books.

If you need the whole page rather than the matching window, take the `bookId` and `pageId` from a result and pass them to `shamela_read` (`unit: 'page'`). `shamela_read` (`unit: 'range'`) and `shamela_read` (`unit: 'section'`) read further — see [the full tool surface](https://qurangallery.com/docs/mcp/tools).

## Next steps

- [Open Quran Gallery MCP](https://qurangallery.com/mcp)
- [MCP API key and bearer token setup for each client](https://qurangallery.com/docs/mcp/bearer-token-setup)
- [MCP tools for classical Arabic books: the full list](https://qurangallery.com/docs/mcp/tools)
- [MCP server for Islamic texts: what it does](https://qurangallery.com/docs/mcp/overview)
