asksakina-mcp

# AskSakina Islamic Knowledge MCP Server

[![npm version](https://img.shields.io/npm/v/@asksakina/islamic-knowledge-mcp.svg?style=flat-square)](https://www.npmjs.com/package/@asksakina/islamic-knowledge-mcp)
[![License](https://img.shields.io/badge/license-Sacred%20Use-8B6A42.svg?style=flat-square)](./LICENSE)
[![MCP Registry](https://img.shields.io/badge/MCP-com.asksakina%2Fislamic--knowledge-4A6B4A.svg?style=flat-square)](https://registry.modelcontextprotocol.io/v0/servers?search=com.asksakina)

> **Specialist-AI-reviewed Islamic knowledge for AI agents.** Quranic verses, a curated du'a collection, and the 99 Names of Allah — reviewed across the four mainstream Sunni schools (Hanafi, Maliki, Shafi'i, Hanbali) through AskSakina's structured specialist-AI review chain, which is not a substitute for a qualified scholar. Every response is wrapped in a presentation contract so agents cannot silently misrepresent the content.

**Architectural posture:** *"AskSakina ships records, agents ship answers."* The server is a reference library, not an advisor. Each response includes a `_sakina_meta` envelope with disclaimer, LLM directives, presentation contract, and educational context. What the calling agent does with the record is its responsibility — but every response arms the agent with enough structural context to make mishandling difficult and trackable.

---

## What it provides

Four lookup tools and one canonical resource over the Model Context Protocol. Every record is sourced from AskSakina's main app (`asksakina.com`), so the MCP server can never drift from what the public app surfaces.

| Tool | What it does |
|---|---|
| `get_quran_verse` | Verbatim Quranic verse lookup by surah:ayah |
| `get_dua` | Curated du'a collection lookup by life context (anxiety, morning, travel, ...) |
| `get_name_of_allah` | One of the 99 Names by number (1–99) or string |
| `find_verses` | Quran verses by topic keyword, from AskSakina's thematic verse index |
| `sakina://about` (resource) | Read-once briefing — seven core directives plus three Gem-cleared dawah texts (Quran preservation, hadith grading, madhab attribution) |

---

## Tools

### `get_quran_verse`

Verbatim Quranic verse lookup by surah:ayah. Returns the canonical AskSakina envelope with Arabic text, translation, surah name (Arabic + English), and the `quran` presentation contract — no paraphrasing, surah:ayah citation required, "Translation of the Meaning" labelling.

**Parameters**

| Name | Type | Required | Notes |
|---|---|---|---|
| `surah` | `1`..`114` | yes | Surah number |
| `ayah` | `1`..`286` | yes | Ayah within the surah |
| `locale` | `'en'` \| `'id'` \| `'ur'` \| `'ar'` | no, defaults `en` | Translation language. `ar` returns the Arabic original with the Pickthall English alongside. Urdu and Indonesian translations are not yet available (pending licences): `ur` and `id` return Pickthall English, `translation_language: "en"` and a `translation_note` saying so |

**Example response (truncated)**

```jsonc
{
  "_sakina_meta": {
    "version": "1.0",
    "content_type": "quran_verse",
    "presentation_contract": {
      "quran": {
        "no_paraphrase": true,
        "require_citation": "surah:ayah",
        "translation_label": "Translation of the Meaning"
      }
    }
    /* … */
  },
  "content": {
    "surah": { "number": 2, "name_arabic": "البقرة", "name_english": "Al-Baqarah" },
    "ayah": 186,
    "arabic": "وَإِذَا سَأَلَكَ عِبَادِي عَنِّي فَإِنِّي قَرِيبٌ ۖ …",
    "translation": "And when My servants ask you concerning Me — indeed I am near. …"
  }
}
```

### `get_dua`

Returns du'as matching a life context (anxiety, grief, morning, travel, etc.). Context is resolved against canonical category slugs, an alias map, and tag dimensions. A natural phrase ("grief after losing my mother") also resolves: the server normalises it and matches known category, alias, tag and synonym words and a few multi-word phrases inside it, deterministically and without AI. `content.matched_by` says how it resolved. **Grief (WO#386):** a query that names the querier's own grief ("I lost my mother", "grief after losing my mother", "my father passed away", "bereaved") resolves to context `bereaved`; a funeral rite or the person who has died ("funeral", "dua for the deceased", "grave") stays `deceased`. `bereaved` returns seven du'as ruled by the fiqh reviewer (Gem 4), in its order, with a `teaching_note` on the masculine forms in the Arabic, and always carries at least the soft support note. Crisis detection runs first, on the full raw input. Self-harm and abuse get separate blocks (`crisis_type`): the abuse block carries domestic-abuse lines and an abuse-specific directive. **On an abuse disclosure no du'as are returned**: `content_type` is `crisis_resource_only` and the crisis resource is the whole response. Each block lists 24/7 lines first and states the hours of any limited-hours line. **If the context contains a crisis keyword (matched against the main app's `detectCrisis` keyword list), the response includes a mandatory `crisis_resource` block** with the appropriate hotline and prosocial directive.

**Parameters**

| Name | Type | Required | Notes |
|---|---|---|---|
| `context` | `string` | yes | Free-form life context |
| `locale` | `'en'` \| `'id'` \| `'ur'` \| `'ar'` | no, defaults `en` | Translation language |

**Example response (truncated)**

```jsonc
{
  "_sakina_meta": {
    "content_type": "dua_collection",
    "presentation_contract": {
      "hadith": { "require_grading": "per_record" /* true when every record is graded */ }
    }
    /* … */
  },
  "content": {
    "context": "stress-anxiety",
    "duas": [
      {
        "dua_block": "Arabic: …\nTransliteration: …\nTranslation: …\nOrigin: Quran 21:87\nSource: Quran 21:87\nGrading: Quranic",
        "title": "Dua to Deal with Distress & Depression",
        "arabic": "وَذَا ٱلنُّونِ إِذ ذَّهَبَ …",
        "source": "Quran 21:87",
        "grading": "Quranic",
        "grading_status": "quranic",
        "origin": "quran",
        "quran_citation": "Quran 21:87"
      },
      {
        "title": "Dua to Remove Sorrow & Grief:",
        "source": "Source not recorded in AskSakina corpus",
        "grading": "Not graded in AskSakina corpus",
        "grading_status": "not_recorded"
        /* … */
      }
      /* … */
    ],
    "total_results": 12,
    "grading_summary": { "quranic": 2, "graded": 0, "not_recorded": 10 }
  }
  // crisis_resource block added if context triggers the crisis keyword list
}
```

**Grading status.** Every du'a record carries `grading_status`: `quranic` (the text is a Quranic verse or clause), `graded` (a hadith grading is recorded), or `not_recorded` (the AskSakina corpus holds no grading for it). Most of the corpus is `not_recorded` today; the `Source` and `Grading` lines say so rather than implying a grading exists. Du'as whose Quranic reference has been verified carry `origin: "quran"` and a `quran_citation`, and their Arabic is the Tanzil Uthmani text resolved from AskSakina's scripture module at bundle time.

### `get_name_of_allah`

Look up by number (1–99) or string (transliteration, Arabic, or English meaning). Returns Arabic, transliteration, locale-aware meaning, reflection, and Quranic references.

**Parameters** — one of:

| Name | Type | Notes |
|---|---|---|
| `number` | `1`..`99` | Primary lookup |
| `name` | `string` | Transliteration, Arabic, or English meaning |

Plus optional `locale`.

**Example response (truncated)**

```jsonc
{
  "_sakina_meta": { "content_type": "name_of_allah" /* … */ },
  "content": {
    "number": 29,
    "arabic": "الحَكَم",
    "transliteration": "Al-Hakam",
    "meaning": "The Judge",
    "reflection": "Allah is the absolute Judge…",
    "quran_references": ["6:114", "13:41"]
  }
}
```

### `find_verses`

Topic lookup beside `get_quran_verse`'s reference lookup (WO#386). The query is normalised and each word is matched to a theme of AskSakina's thematic verse index (anxiety, gratitude, patience, trust, grief, hope, forgiveness, morning, friday, ramadan, encouragement), by theme name or a fixed synonym list. Deterministic: no embedding, no AI call.

Each verse carries `reference` (surah:ayah), `arabic` (the full ayah from the scripture module, Tanzil Uthmani, byte for byte), `translation` (full-ayah Pickthall, fetched as `get_quran_verse` fetches it), the surah names, and a `relevance_note` saying which theme lists it. The note is not commentary. If the upstream is unreachable, the Arabic is still served and `translation` is `null` with a note.

No match returns `content_type: "not_found"` with `verses: []`, `no_results: true` and the list of available themes, not an error. Crisis detection runs first, as on `get_dua`: an abuse disclosure returns `crisis_resource_only` with no verses, and any other crisis keyword returns its block with no verses inferred from the message.

**Parameters**

| Name | Type | Required | Notes |
|---|---|---|---|
| `query` | `string` | yes | Topic or keyword, e.g. `patience`, `grief`, `gratitude` |
| `limit` | `1`..`10` | no, defaults `5` | Number of verses |
| `locale` | `'en'` \| `'id'` \| `'ur'` \| `'ar'` | no, defaults `en` | Selects the in-country crisis resources. Translations are Pickthall English; `ur` and `id` carry the parked-translation note |

### Resource: `sakina://about`

Read this resource **before** using the tools. It contains the seven core directives plus three Gem-cleared educational dawah texts. Most MCP clients fetch it automatically the first time they connect.

---

## Response envelope

Every tool returns the same shape:

```jsonc
{
  "_sakina_meta": {
    "version": "1.0",
    "source": "AskSakina Islamic Knowledge Server (asksakina.com)",
    "content_type": "quran_verse" | "dua_collection" | "name_of_allah" | "not_found" | "crisis_resource_only",
    "disclaimer": "AskSakina provides curated Islamic reference content for educational purposes. …",
    "llm_directives