# Islamic Sources (@IslamicSources) — Full Technical Reference (`llms-full.txt`) > Comprehensive, unabridged technical documentation and tool schema catalog for Islamic Sources (@IslamicSources) on the Waqf MCP Gateway (`mcp.waqf.app`). --- ## 1. Overview & Architecture Islamic Sources (@IslamicSources) is an edge-native federation gateway connecting Muslim developers, researchers, and AI agents to authentic Islamic sources. It runs on Cloudflare Workers (stateless V8 isolates) and Cloudflare D1 SQLite. ### Key Architectural Tenets 1. **Neutral Aggregator & As-Is Transmission**: Operates strictly as a federated aggregator and proxy. The gateway does not author, add, edit, or alter any response or text from upstream Islamic data providers. Content is relayed verbatim from original sources, and the service is provided strictly on an "as is" basis without warranties. 2. **Stateless Edge Runtime**: Employs Streamable HTTP / JSON-RPC 2.0 without Durable Objects. No stateful connection leases. 3. **Deterministic SHA-256 Edge Caching**: Immutable Islamic texts (Quranic verses, Hadiths, Tafsirs) and search queries are hashed and cached in Cloudflare D1 (`mcp_cache`). Latency for cached hits is typically `< 15ms`. 4. **Non-blocking Telemetry**: Gateway logs (anonymized IP hash, Geo, ASN, latency, tool, error status) are written asynchronously using Cloudflare's `ctx.waitUntil()`. Telemetry overhead on the response stream is zero milliseconds. 5. **Collision Defense**: Upstream server tools are namespaced (e.g. `bahouth__get_verse`, `tafsir_net__fetch_ayah`, `turath__get_book`, `fihris__search_islamic_sources`) while canonical adapters provide unified interfaces (`waqf_quran_get_ayah`, `waqf_hadith_search`, `waqf_turath_search_books`, `waqf_search_scholarship`). 6. **Bidirectional Loop Prevention**: Gateway requests to upstream servers include the header `X-Waqf-Federated-By: mcp.waqf.dev`. If an upstream worker forwards queries, this header breaks infinite cycles. --- ## 2. Endpoints & Connectivity | Protocol | URL | Method | Content-Type / Accept | Purpose | | :--- | :--- | :---: | :--- | :--- | | **Streamable HTTP** | `https://mcp.waqf.app/mcp` | `POST` | `application/json` | Primary MCP JSON-RPC 2.0 endpoint | | **Server-Sent Events** | `https://mcp.waqf.app/sse` | `GET` | `text/event-stream` | MCP SSE transport stream | | **Discovery** | `https://mcp.waqf.app/` | `GET` | `application/json` | Health check & provider metadata | | **Web Portal** | `https://mcp.waqf.dev/` | `GET` | `text/html` | Multilingual portal (ar, en, tr, id, ms) | | **LLM Index** | `https://mcp.waqf.app/llms.txt` | `GET` | `text/plain` | Concise LLM overview & quickstart | | **LLM Full Catalog** | `https://mcp.waqf.app/llms-full.txt` | `GET` | `text/plain` | Exhaustive tool catalog & schemas | ### WAF Bot Protection Cloudflare Web Application Firewall automatically blocks default bot User-Agents (such as `Python-urllib/3.x` or headless curl patterns). **Always pass an explicit `User-Agent` header** in programmatic HTTP requests: ``` User-Agent: MyAgentName/1.0 (+https://example.com) ``` --- ## 3. Query Profiles & Context Presets To prevent prompt context window exhaustion, append the `?suite=` parameter to the MCP endpoint: ### A. `?suite=core` (Recommended for AI Agents) Exposes only the 6 canonical, high-level normalized tools. Context overhead: ~1,400 tokens. - `waqf_quran_get_ayah` - `waqf_hadith_search` - `waqf_turath_search_books` - `waqf_search_scholarship` - `waqf_books_search` - `waqf_books_read_page` ### B. `?suite=quran` Exposes Quranic, Tafsir, linguistic, and morphological tools from **Bahouth** and **Tafsir.net**. - Canonical: `waqf_quran_get_ayah` - Bahouth: `bahouth__*` (9 tools) - Tafsir.net: `tafsir_net__*` (17 tools) ### C. `?suite=turath` Exposes classical Hadith collections, Islamic heritage libraries, the Aljam3 books corpus, and scholarly verification tools from **Turath**, **Sheikh Maher Al-Fahel** and **Aljam3**. - Canonical: `waqf_hadith_search`, `waqf_turath_search_books`, `waqf_books_search`, `waqf_books_read_page` - Turath: `turath__*` (5 tools) - Maher Al-Fahel: `maheralfahel__*` (5 tools) - Aljam3: `aljam3__*` (7 tools) ### D. `?suite=search` Exposes verified academic web search across 38+ authentic Islamic portals from **Fihris**. - Canonical: `waqf_search_scholarship` - Fihris: `fihris__*` (2 tools) ### E. Default (`?suite=all` or omitted) Exposes all 51 tools across all 6 federated providers. --- ## 4. Complete Tool Catalog & Schemas ### Group 1: Canonical Unified Tools (`waqf_*`) #### `waqf_quran_get_ayah` Lookup a verified Holy Quran Ayah by Surah and Ayah number, with optional authentic Tafsir. - **Input Schema**: ```json { "type": "object", "properties": { "surah": { "type": "number", "description": "Surah number (1-114)", "minimum": 1, "maximum": 114 }, "ayah": { "type": "number", "description": "Ayah number (1-286)", "minimum": 1 }, "includeTafsir": { "type": "boolean", "description": "Whether to include tafsir explanation (default: true)" }, "tafsirSource": { "type": "string", "description": "Tafsir source key (e.g. 'almukhtasar', 'al-tabari', 'ibn-kathir', 'al-saadi', 'al-qurtubi')" } }, "required": ["surah", "ayah"] } ``` #### `waqf_hadith_search` Search classical Hadith and scholarly Islamic literature using semantic or lexical queries. - **Input Schema**: ```json { "type": "object", "properties": { "query": { "type": "string", "description": "Hadith text, topic, or keyword in Arabic or English" }, "book": { "type": "string", "description": "Filter by primary Hadith collection (e.g. 'bukhari', 'muslim', 'tirmidhi', 'abu-dawood')" }, "limit": { "type": "number", "description": "Maximum number of hadiths to return (default: 5)" } }, "required": ["query"] } ``` #### `waqf_turath_search_books` Search the vast Turath Islamic library catalog for classical books, treatises, and manuscripts. - **Input Schema**: ```json { "type": "object", "properties": { "query": { "type": "string", "description": "Book title, author, or subject keyword in Arabic" }, "category": { "type": "string", "description": "Optional category filter (e.g. 'تفسير', 'حديث', 'فقه', 'عقيدة')" }, "limit": { "type": "number", "description": "Maximum books to return (default: 10)" } }, "required": ["query"] } ``` #### `waqf_search_scholarship` Search across 38+ authentic Islamic scholarship portals (fatwas, research, classical treatises) using Fihris Islamic Search. - **Input Schema**: ```json { "type": "object", "properties": { "query": { "type": "string", "description": "Search keywords or question in Arabic or English (e.g. 'شروط الصلاة', 'صيام يوم عاشوراء')" }, "fileType": { "type": "string", "enum": ["pdf", "doc", "docx", "txt"], "description": "Optional file type filter" }, "dateRestrict": { "type": "string", "enum": ["d1", "w1", "m1", "y1"], "description": "Optional date restriction (d1 = past 24h, w1 = past week, m1 = past month, y1 = past year)" }, "page": { "type": "number", "description": "Page number for pagination (default: 1)" } }, "required": ["query"] } ``` #### `waqf_books_search` Search inside the full text of classical Islamic books (the Aljam3 corpus) and return short matching passages with book, author, file and page metadata plus a direct link to the source. - **Input Schema**: ```json { "type": "object", "properties": { "query": { "type": "string", "description": "Search terms, usually in Arabic; a quoted phrase searches for that exact phrase" }, "page": { "type": "number", "description": "Result page to return (default: 1, max: 100)" }, "limit": { "type": "number", "description": "Number of passages per result page (default: 10, max: 20)" }, "bookId": { "type": "number", "description": "Restrict to one book" }, "authorId": { "type": "number", "description": "Restrict to one author" }, "categoryId": { "type": "number", "description": "Restrict to one subject" }, "libraryId": { "type": "number", "description": "Restrict to one source collection" }, "locale": { "type": "string", "enum": ["ar", "ur", "en"], "description": "Language of the returned links" } }, "required": ["query"] } ``` #### `waqf_books_read_page` Read one exact page of a digitized book in context, with citation metadata, a PDF link and neighbouring page numbers. Long pages are chunked: repeat with the returned next offset to continue. - **Input Schema**: ```json { "type": "object", "properties": { "fileId": { "type": "number", "description": "Book file ID, from waqf_books_search" }, "pageNumber": { "type": "number", "description": "Page number within that file" }, "offset": { "type": "number", "description": "Character offset to continue from (default: 0)" }, "maxChars": { "type": "number", "description": "Maximum characters of page text (default: 6000, max: 12000)" }, "locale": { "type": "string", "enum": ["ar", "ur", "en"], "description": "Language of the returned links" } }, "required": ["fileId", "pageNumber"] } ``` --- ### Group 2: Tafsir Center for Quranic Studies (`tafsir_net__*`) Upstream: `https://mcp.tafsir.net/mcp` (SSE) 1. `tafsir_net__fetch_ayah`: Get Uthmani text of a specific Quran verse (`surah_number`, `ayah_number`). 2. `tafsir_net__fetch_tafsir`: Fetch scholarly tafsir from one or multiple verified sources (`surah_number`, `ayah_number`, `source_slug`). 3. `tafsir_net__list_tafsir_sources`: List all available Tafsir sources and their authors. 4. `tafsir_net__list_science_sources`: List Quranic sciences sources (Asbab al-Nuzul, I'rab, Qira'at). 5. `tafsir_net__list_all_sources`: List every content source in the Tafsir.net database. 6. `tafsir_net__list_sources_for_ayah`: Check which tafsir sources cover a specific ayah. 7. `tafsir_net__fetch_nuzool_reason`: Fetch verified reasons for revelation (Asbab al-Nuzul). 8. `tafsir_net__fetch_surah_info`: Comprehensive metadata on a Surah (names, Makki/Madani status, core themes). 9. `tafsir_net__analyze_word`: Morphological, grammatical, and root analysis of a specific word in an Ayah. 10. `tafsir_net__find_root_occurrences`: Locate all occurrences of a linguistic root in the Quran. 11. `tafsir_net__get_root_stats`: Statistical occurrences and derivation counts of a root. 12. `tafsir_net__get_qeraat_variants`: Recitation variants across the 10 Mutawatir Qira'at. 13. `tafsir_net__search_quran_text`: Full-text search with diacritics support. 14. `tafsir_net__search_in_tafsir`: Full-text search within specific tafsir books. 15. `tafsir_net__get_quran_overview`: Macro-level statistics of the Quran (ayahs, words, letters, surahs). 16. `tafsir_net__get_page_fawaed`: Contemplative benefits (Fawa'id) from al-Mukhtasar for a Mushaf page. 17. `tafsir_net__get_surah_statistics`: Word and character counts, vocabulary density for a Surah. #### Tafsir Center Resources (`resources/list`, `resources/read`) Accessible directly or via the gateway: 1. `quran://surahs` (`surahs_catalog`): Index of all 114 Surahs with metadata (JSON). 2. `quran://tafsirs` (`tafsirs_catalog`): Index of 28 Tafsir sources with author death years and isnad coverage (JSON). 3. `quran://sciences` (`sciences_catalog`): Index of Quranic science sources (I'rab, Asbab al-Nuzul, Gharib, Qira'at, Tadabbur) (JSON). 4. `quran://schema` (`schema_documentation`): Complete database schema documentation for developers (Markdown). #### Tafsir Center Prompts (`prompts/list`, `prompts/get`) Standardized prompt templates ready for LLM invocation: 1. `study_ayah`: Ayah study template combining text, I'rab, Tafsir, and word vocabulary (`surah`, `ayah`). 2. `compare_tafsirs`: Comparative tafsir template across the 5 primary works (`surah`, `ayah`). 3. `root_study`: In-depth study of an Arabic root, occurrences, patterns, and contexts (`root`). 4. `surah_overview`: Comprehensive Surah overview (themes, virtues, statistics) (`surah`). 5. `tajweed_lesson`: Tajweed study lesson with rules, Qira'at variants, and word breakdown (`surah`, `ayah`). --- ### Group 3: Bahouth Quran & Tafsir Project (`bahouth__*`) Upstream: `https://bahouth.tafsir.net/mcp` (JSON-RPC) 1. `bahouth__get_verse`: Fetch a verse by verse key (e.g. `"2:255"` or `"2-255"`). 2. `bahouth__list_surah_verses`: Return all verses of a Surah with order indices. 3. `bahouth__list_verse_words`: Return ordered word occurrences, lemmas, and root associations. 4. `bahouth__find_root`: Lookup root dictionary entry and semantic associations. 5. `bahouth__list_root_verses`: Paginated list of verses containing derivations of a root. 6. `bahouth__list_verse_properties`: Linguistic, phonetic, and orthographic properties of a verse. 7. `bahouth__list_verse_qiraat`: Qira'at recitation variances for a verse. 8. `bahouth__list_verse_topics`: Thematic classification tags attached to an Ayah. 9. `bahouth__list_topic_verses`: Retrieve all verses addressing a specific thematic topic. --- ### Group 4: Turath Islamic Heritage Library (`turath__*`) Upstream: `https://mcp.turath.io/mcp/` (JSON-RPC) 1. `turath__discover_turath`: Discover books, categories, and scholarly eras. 2. `turath__search_turath`: Full-text search across classical Islamic literature collections. 3. `turath__get_book`: Retrieve metadata, volume list, and publisher details for a work. 4. `turath__get_page`: Retrieve verbatim page text by book ID, volume number, and page number. 5. `turath__get_author`: Retrieve biographical metadata, dates, and bibliography for classical scholars. --- ### Group 5: Sheikh Maher Al-Fahel Scholarly Library (`maheralfahel__*`) Upstream: `https://maheralfahel.net/mcp/` (SSE) 1. `maheralfahel__list-books`: List all published books and verified treatises. 2. `maheralfahel__get-book`: Detailed book table of contents, volumes, and downloads. 3. `maheralfahel__list-media`: Catalog of scientific lectures, Hadith explanation videos, and audio sessions. 4. `maheralfahel__search-content`: Search across Sheikh Maher's articles, fatwas, and publications. 5. `maheralfahel__get-site-info`: Metadata about the scholarly center and methodology. --- ### Group 6: Fihris Islamic Web Search (`fihris__*`) Upstream: `https://search.waqf.app/api/mcp` (JSON-RPC) 1. `fihris__search_islamic_sources`: Search across 38+ vetted Islamic scholarship portals (e.g. Alukah, Dorar, IslamQA, Bin Baz, Ibn Uthaymeen, Majallat al-Buhuth). 2. `fihris__list_indexed_sources`: List all 38+ indexed scholar websites, institutions, and portals. --- ### Group 7: Aljam3 Islamic Books Library (`aljam3__*`) Upstream: `https://aljam3.com/mcp` (JSON-RPC, read-only, no authentication) 1. `aljam3__search`: Search the text of public books by topic, phrase or quotation; combines book, author, subject and library filters and returns excerpts with source metadata and exact page URLs. 2. `aljam3__list_books`: Browse public books or search their titles, filtered by author, subject or source library. 3. `aljam3__get_book`: Book metadata plus a paginated list of its files in reading order with PDF/TXT/DOCX downloads and first page numbers. 4. `aljam3__get_page`: Read the stored text of an exact page (`file_id`, `page_number`) with citation metadata, a PDF page link and adjacent page numbers; long text is chunked, repeat with `offset` to continue. 5. `aljam3__list_authors`: Browse or search authors and their IDs. 6. `aljam3__list_categories`: Browse or search subject categories. 7. `aljam3__list_libraries`: List the source collections available in Aljam3. Notes: page numbers refer to the digitized file, not necessarily the printed edition; extracted text may contain OCR errors, so verify important quotations against the PDF. Canonical entry points: `waqf_books_search` and `waqf_books_read_page`. --- ## 5. JSON-RPC 2.0 Request & Response Protocol All interactions with `POST /mcp` strictly follow the JSON-RPC 2.0 specification. ### Tool Call Example ```http POST /mcp?suite=core HTTP/1.1 Host: mcp.waqf.app Content-Type: application/json User-Agent: MyResearchAgent/1.0 { "jsonrpc": "2.0", "id": "req-001", "method": "tools/call", "params": { "name": "waqf_quran_get_ayah", "arguments": { "surah": 112, "ayah": 1, "includeTafsir": true, "tafsirSource": "almukhtasar" } } } ``` ### Response Example (Actual Gateway Output) ```json { "jsonrpc": "2.0", "id": "req-001", "result": { "isError": false, "content": [ { "type": "text", "text": "[Source: Tafsir.net]\n{\n \"surah\": 112,\n \"ayah\": 1,\n \"text\": \"قل هو الله أحد\",\n \"text_uthmani\": \"قل هو الله أحد\",\n \"text_simple\": \"قل هو الله أحد\",\n \"tajweed\": null,\n \"irab\": null,\n \"word_count\": 4,\n \"gharib\": \"﴿ هُوَ ٱللَّهُ أَحَدٌ ﴾: هُو اللهُ المتفرِّدُ بالأُلُوهِيَّةِ والرُّبُوبِيَّةِ والأسْماءِ والصِّفاتِ، لا يُشارِكُه أَحَدٌ فِيها.\",\n \"tadabbur\": \"اعلم أيها المسلمُ أن ربَّك متفرِّد في عَليائه وصفاته، ومنزَّهٌ عن كلِّ عيب ونقص، فأقبِل عليه بقلبك وعقلك، وسَله الهدايةَ والثبات؟\\nــــــــــــــــــــــــــــــــــــــــــــــــ\\nفي أمر الله لنبيِّه ﷺ بأن يبيِّنَ للعالمين تفرُّدَه سبحانه في صفات الجلال والكمال، أمرٌ لكلِّ مسلم، وهو من أعظم الجهاد.\",\n \"_display\": \"اعرض هذا النص حرفياً وكاملاً بين علامتي اقتباس مع ذكر النسبة (attribution): (١) انسخ كل حرف كما ورد — بما فيه ترويسة المؤلف في مطلع السورة (مثل «تفسير سورة الناس وهي مدنية») والبسملة، وعلامات الهوامش مثل {[1]} و{[2]}، وجهاز النقد ¬...¥ (فروق النسخ)؛ كلها محتوى علمي من النص — لا تُسقِط شيئاً بوصفه «عنواناً» أو «رمزاً» أو «بيانات». (٢) لا تختصر ولا تلخّص ولا تُعِد الصياغة ولا تترجم، ولو بدا النص قصيراً؛ إن طال فاستعمل التقسيم (part/total_parts) لا التلخيص.\"\n}" } ] } } ``` ### Standard Error Envelopes (Actual Gateway Output) If a protocol method is unknown or invalid, the gateway returns a standard JSON-RPC 2.0 error: ```json { "jsonrpc": "2.0", "id": "req-err-02", "error": { "code": -32601, "message": "Method 'unknown_method' not found" } } ``` If an upstream tool call fails (e.g. invalid arguments or range violation), the gateway returns an MCP tool execution error (`isError: true`): ```json { "jsonrpc": "2.0", "id": "req-err-01", "result": { "isError": true, "content": [ { "type": "text", "text": "[Source: Bahouth]\nError executing tool get_verse: verse_key is outside the supported Quranic range" } ] } } ``` | Code | Meaning | Cause | | :---: | :--- | :--- | | `-32700` | Parse Error | Invalid JSON sent to `/mcp` | | `-32600` | Invalid Request | Request is not a valid JSON-RPC 2.0 object | | `-32601` | Method Not Found | Requested method is not supported (supported: initialize, ping, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get) | | `-32602` | Invalid Params | Missing required arguments or schema type violation | | `-32603` | Internal Error | Upstream provider timeout or unreachable | --- ## 6. Multi-Language Developer Snippets ### Python (`httpx`) ```python import httpx headers = { "User-Agent": "WaqfAgent/1.0 (https://waqf.dev)", "Content-Type": "application/json", } # 1. List available tools in core suite resp = httpx.post( "https://mcp.waqf.app/mcp?suite=core", json={"jsonrpc": "2.0", "id": 1, "method": "tools/list"}, headers=headers, timeout=10.0, ) tools = resp.json()["result"]["tools"] print(f"Available tools: {[t['name'] for t in tools]}") # 2. Search scholarly fatwas and research query_resp = httpx.post( "https://mcp.waqf.app/mcp?suite=core", json={ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "waqf_search_scholarship", "arguments": {"query": "حكم صلاة الكسوف"} } }, headers=headers, timeout=15.0, ) print(query_resp.json()["result"]["content"][0]["text"]) ``` ### Node.js / TypeScript (`@modelcontextprotocol/sdk`) ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHttpClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const transport = new StreamableHttpClientTransport( new URL("https://mcp.waqf.app/mcp?suite=core"), { headers: { "User-Agent": "WaqfNodeAgent/1.0", }, } ); const client = new Client({ name: "MyClient", version: "1.0.0" }, { capabilities: {} }); await client.connect(transport); const result = await client.callTool({ name: "waqf_quran_get_ayah", arguments: { surah: 2, ayah: 255 }, }); console.log(result.content[0].text); ``` --- ## 7. Licensing & Open-Source Governance The Waqf MCP Federation Gateway is published under the **Digital Waqf Public License (Waqf-DPL 1.0)** by the [WaqfTech Foundation](https://waqftech.org/). - **Scope of License**: The Waqf-DPL 1.0 applies strictly to the gateway aggregator code and technical federation infrastructure, not to the underlying Islamic content or texts. - **Provider Independence**: WaqfTech does not own, manage, or operate the federated upstream MCP servers. Each provider retains its own independent license, copyright, and terms of use, which must be verified directly at its source. - Source Code: [github.com/waqftech/waqf-mcp](https://github.com/waqftech/waqf-mcp) - License Draft: [github.com/WaqfTech/waqf-license-draft](https://github.com/WaqfTech/waqf-license-draft) - Contributions: Pull requests, new provider adapter submissions, and bug reports are warmly welcomed on GitHub.