# Islamic Sources (@IslamicSources) — Waqf MCP Gateway (`mcp.waqf.app`)

> An edge-native Model Context Protocol (MCP) gateway aggregating authentic Islamic knowledge sources (Quran, Hadith, Tafsir, Turath heritage literature, and scholarly search) into a single, unified interface for AI assistants (invoked with `@IslamicSources`), IDEs, and autonomous agents.

Islamic Sources (@IslamicSources) federates independent Islamic MCP servers into one endpoint (`https://mcp.waqf.app/mcp`), unifies divergent schemas, caches immutable texts in Cloudflare D1 SQLite, and provides token-optimized query profiles to prevent agent context window bloat.

## Quick Links

- [Full Technical Reference (llms-full.txt)](https://mcp.waqf.app/llms-full.txt): Complete tool schemas, parameters, and comprehensive integration guide.
- [Web Portal](https://mcp.waqf.dev/): Multi-lingual landing page with interactive setup guides and documentation.
- [GitHub Repository](https://github.com/waqftech/waqf-mcp): Open-source monorepo.
- [License (Waqf-DPL 1.0)](https://github.com/WaqfTech/waqf-license-draft): Digital Waqf Public License.
- [WaqfTech Foundation](https://waqftech.org/): Open-source Islamic technology foundation.

## Aggregator & As-Is Transmission Notice

> **IMPORTANT**: Islamic Sources (@IslamicSources) is strictly an aggregator and neutral edge gateway.
> - **Independence & Ownership**: We do not own, manage, or operate the independent MCP servers federated in our aggregator, nor are we affiliated with their operations.
> - **Licensing Scope**: The Waqf Digital Public License (Waqf-DPL) applies strictly to the gateway aggregator software and technical infrastructure, not to the underlying Islamic content or texts. Each upstream MCP server retains its own independent license and terms of use, which must be consulted directly at the source.
> - **Zero Alteration**: We do not author, add, edit, or alter responses or texts from the underlying Islamic sources. All Quranic verses, Hadith narrations, Tafsir commentaries, and scholarly search results are relayed verbatim from their original upstream providers.
> - **Provided "As Is"**: This service is provided on an "as is" and "as available" basis without warranties of any kind. For authoritative scholarly verification, consult the respective source institutions directly.

## Connection Endpoints

- **Streamable HTTP (JSON-RPC 2.0)**: `POST https://mcp.waqf.app/mcp`
- **Server-Sent Events (SSE)**: `GET https://mcp.waqf.app/sse` (or `GET /mcp` with `Accept: text/event-stream`)
- **Gateway Discovery**: `GET https://mcp.waqf.app/` (returns health status, federated providers, available suites)
- **Authentication**: None required for public MCP tools. Completely open and free of charge.

> ⚠️ **Cloudflare WAF Bot Notice**: When calling `https://mcp.waqf.app/mcp` programmatically, always include a custom `User-Agent` header (e.g. `User-Agent: my-agent/1.0`). Generic default scrapers like `Python-urllib` are blocked by Cloudflare WAF.

## Query Profiles (Agent Context Optimization)

Loading 50+ tools into an LLM's system prompt consumes excessive context tokens. Waqf MCP supports targeted suites via the `?suite=` query parameter:

- `https://mcp.waqf.app/mcp?suite=core` **[RECOMMENDED FOR AGENTS]**: Exposes only high-level canonical tools (~1,400 tokens total).
- `https://mcp.waqf.app/mcp?suite=quran`: Exposes Quran, Tafsir, and Arabic root analysis tools.
- `https://mcp.waqf.app/mcp?suite=turath`: Exposes classical Islamic heritage books, the Aljam3 books corpus, Hadith critique, and scholarly libraries.
- `https://mcp.waqf.app/mcp?suite=search`: Exposes verified academic Islamic web search (Fihris).
- `https://mcp.waqf.app/mcp` (or `?suite=all`): Full federation suite with all 51 tools across all 6 providers.

## Federated Providers

1. **Tafsir Center for Quranic Studies** (`tafsir_net`):
   - Host: `https://mcp.tafsir.net/mcp` (SSE)
   - Scope: 17 specialized tools (al-Mukhtasar, al-Tabari, Ibn Kathir, al-Sa'di, Asbab al-Nuzul, Qira'at variants, word morphology, FTS5 Quran search, root stats).
   - Resources: `quran://surahs`, `quran://tafsirs`, `quran://sciences`, `quran://schema`.
   - Prompts: `study_ayah`, `compare_tafsirs`, `root_study`, `surah_overview`, `tajweed_lesson`.
2. **Bahouth Quran & Tafsir Project** (`bahouth`):
   - Host: `https://bahouth.tafsir.net/mcp` (JSON-RPC)
   - Scope: Quranic root search, morphological analysis, verse words, thematic topics, and verse lookups.
3. **Turath Islamic Heritage Library** (`turath`):
   - Host: `https://mcp.turath.io/mcp/` (JSON-RPC)
   - Scope: Search across tens of thousands of classical volumes, Hadith compendia, fiqh treatises, author biographies, and page-level text extraction.
4. **Sheikh Maher Al-Fahel Scholarly Library** (`maheralfahel`):
   - Host: `https://maheralfahel.net/mcp/` (SSE)
   - Scope: Hadith sciences (Mustalah al-Hadith), scholarly verification (Tahqiq), verified publications, and audio/video lectures.
5. **Fihris Islamic Web Search** (`fihris`):
   - Host: `https://search.waqf.app/api/mcp` (JSON-RPC)
   - Scope: Curated Google Custom Search across 38+ authentic Islamic scholarship portals, academic research journals, and verified fatwa councils.
6. **Aljam3 Islamic Books Library** (`aljam3`):
   - Host: `https://aljam3.com/mcp` (JSON-RPC, read-only, no authentication)
   - Scope: Search the full text of public Islamic books, browse books and their files, and read exact pages with book, author, file and page citations plus direct source and PDF links.

## Canonical Tools Reference (`?suite=core`)

Canonical tools unify divergent upstream interfaces into consistent, standardized tool signatures:

### 1. `waqf_quran_get_ayah`
Lookup a verified Holy Quran Ayah by Surah and Ayah number, with optional authentic Tafsir.
- **Parameters**:
  - `surah` (number, required): Surah number (1–114).
  - `ayah` (number, required): Ayah number (1–286).
  - `includeTafsir` (boolean, optional): Include tafsir explanation (default: `true`).
  - `tafsirSource` (string, optional): Tafsir source key (default: `"almukhtasar"`). Supported: `"almukhtasar"`, `"al-tabari"`, `"ibn-kathir"`, `"al-saadi"`, `"al-qurtubi"`.

### 2. `waqf_hadith_search`
Search classical Hadith and scholarly Islamic literature using semantic or lexical queries.
- **Parameters**:
  - `query` (string, required): Search query in Arabic or English (e.g. `"إنما الأعمال بالنيات"`).
  - `book` (string, optional): Specific book filter (e.g. `"bukhari"`, `"muslim"`, `"tirmidhi"`).
  - `limit` (number, optional): Maximum results to return (default: `5`).

### 3. `waqf_turath_search_books`
Search the vast Turath Islamic library catalog for classical books, treatises, and manuscripts.
- **Parameters**:
  - `query` (string, required): Book title, author name, or topic in Arabic.
  - `category` (string, optional): Optional category filter (e.g. `"تفسير"`, `"حديث"`, `"عقيدة"`, `"فقه"`).
  - `limit` (number, optional): Maximum results (default: `10`).

### 4. `waqf_search_scholarship`
Search across 38+ authentic Islamic scholarship portals (fatwas, research journals, classical treatises) using Fihris Islamic Search.
- **Parameters**:
  - `query` (string, required): Search keywords or question in Arabic or English.
  - `fileType` (string, optional): `"pdf" | "doc" | "docx" | "txt"`.
  - `dateRestrict` (string, optional): `"d1" | "w1" | "m1" | "y1"` (past day, week, month, year).
  - `page` (number, optional): Page number for pagination (default: `1`).

### 5. `waqf_books_search`
Search inside the full text of classical Islamic books (the Aljam3 corpus) and get short passages with book, author, file and page metadata plus a source link.
- **Parameters**:
  - `query` (string, required): Search terms, usually in Arabic; quote a phrase for an exact-phrase search.
  - `page` (number, optional): Result page to return (default: `1`, max: `100`).
  - `limit` (number, optional): Passages per result page (default: `10`, max: `20`).
  - `bookId` | `authorId` | `categoryId` | `libraryId` (number, optional): Restrict the search to one book, author, subject or source library.
  - `locale` (string, optional): `"ar" | "ur" | "en"` — language of the returned links only.

### 6. `waqf_books_read_page`
Read one exact page of a digitized book in context, with citation metadata, a PDF page link and the neighbouring page numbers.
- **Parameters**:
  - `fileId` (number, required): Book file ID, from `waqf_books_search` or `aljam3__get_book`.
  - `pageNumber` (number, required): Page number within that file.
  - `offset` (number, optional): Character offset to continue reading from, using the next offset returned by the previous call.
  - `maxChars` (number, optional): Maximum characters of page text (default: `6000`, max: `12000`).
  - `locale` (string, optional): `"ar" | "ur" | "en"` — language of the returned links only.

## Client Configurations

### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "waqf-islamic-core": {
      "url": "https://mcp.waqf.app/mcp?suite=core"
    }
  }
}
```

### Cursor (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "waqf-islamic-core": {
      "url": "https://mcp.waqf.app/mcp?suite=core"
    }
  }
}
```

### Antigravity / Gemini CLI (`mcp_config.json`)
```json
{
  "mcpServers": {
    "waqf-islamic-core": {
      "url": "https://mcp.waqf.app/mcp?suite=core"
    }
  }
}
```

### Direct JSON-RPC 2.0 Example (cURL)
```bash
curl -s -X POST https://mcp.waqf.app/mcp?suite=core \
  -H "Content-Type: application/json" \
  -H "User-Agent: WaqfAgent/1.0" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "waqf_quran_get_ayah",
      "arguments": { "surah": 1, "ayah": 1 }
    }
  }'
```

### Python Integration (`httpx`)
```python
import httpx

client = httpx.Client(
    base_url="https://mcp.waqf.app",
    headers={"User-Agent": "MyAgent/1.0", "Content-Type": "application/json"}
)

response = client.post("/mcp?suite=core", json={
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "waqf_search_scholarship",
        "arguments": {"query": "شروط الصلاة"}
    }
})
print(response.json()["result"]["content"][0]["text"])
```

## Runtime Architecture & Performance

- **Runtime**: Stateless Cloudflare Workers (V8 Isolate) with Streamable HTTP transport. Zero Durable Objects leased.
- **Edge Cache**: Cloudflare D1 SQLite (`mcp_cache`). Cached queries return in `< 15ms`.
- **Non-blocking Telemetry**: Gateway logs (Geo, ASN, IP hash, latency) execute inside `ctx.waitUntil()` and never block response delivery.
- **Loop Prevention**: Gateway injects `X-Waqf-Federated-By: mcp.waqf.dev` on all upstream requests.