# 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.dev`).

---

## 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.dev/mcp` | `POST` | `application/json` | Primary MCP JSON-RPC 2.0 endpoint |
| **Server-Sent Events** | `https://mcp.waqf.dev/sse` | `GET` | `text/event-stream` | MCP SSE transport stream |
| **Discovery** | `https://mcp.waqf.dev/` | `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.dev/llms.txt` | `GET` | `text/plain` | Concise LLM overview & quickstart |
| **LLM Full Catalog** | `https://mcp.waqf.dev/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 4 canonical, high-level normalized tools. Context overhead: ~1,200 tokens.
- `waqf_quran_get_ayah`
- `waqf_hadith_search`
- `waqf_turath_search_books`
- `waqf_search_scholarship`

### 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, and scholarly verification tools from **Turath** and **Sheikh Maher Al-Fahel**.
- Canonical: `waqf_hadith_search`, `waqf_turath_search_books`
- Turath: `turath__*` (5 tools)
- Maher Al-Fahel: `maheralfahel__*` (5 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 42 tools across all 5 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"]
  }
  ```

---

### 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.

---

### 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.

---

## 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.dev
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 `initialize`, `tools/list`, or `tools/call` |
| `-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.dev/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.dev/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.dev/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.