ayah_search

Search Quran ayahs by Arabic text and render matches in an interactive result list. Matching is diacritic-insensitive, handles typos, and ranks results by relevance.

Text-only counterpart: search_ayahs_text — same search behavior, plain JSON output for intermediate/preparatory steps.

Use This When

• The user asks where a phrase appears in the Quran and wants to explore matches visually.
• The user wants to find an ayah from a remembered Arabic fragment.
• The user asks to browse a ranked list of matches.

For intermediate lookups (e.g., find a key, then play it), prefer search_ayahs_text.

Widget Preview

Submission Scenario

Live-captured prompt, MCP request, and expected response used for the OpenAI submission. Regenerate with bun run capture:submission from the repo root.

{
  "prompt": "Find ayahs that contain الرحمن الرحيم",
  "request": {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ayah_search",
      "arguments": {
        "query": "الرحمن الرحيم",
        "max_results": 5
      }
    }
  },
  "response": {
    "query": "الرحمن الرحيم",
    "total_results": 5,
    "results": [
      {
        "ayah_key": "1:3",
        "chapter": 1,
        "verse": 3,
        "surah_name": "Al-Fatihah",
        "surah_name_arabic": "الفاتحة",
        "ayah_text": "ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ",
        "strategy": "exact"
      },
      {
        "ayah_key": "1:1",
        "chapter": 1,
        "verse": 1,
        "surah_name": "Al-Fatihah",
        "surah_name_arabic": "الفاتحة",
        "ayah_text": "بِسْمِ ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ",
        "strategy": "exact"
      },
      {
        "ayah_key": "41:2",
        "chapter": 41,
        "verse": 2,
        "surah_name": "Fussilat",
        "surah_name_arabic": "فصلت",
        "ayah_text": "تَنزِيلٌ مِّنَ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ",
        "strategy": "exact"
      },
      {
        "ayah_key": "27:30",
        "chapter": 27,
        "verse": 30,
        "surah_name": "An-Naml",
        "surah_name_arabic": "النمل",
        "ayah_text": "إِنَّهُۥ مِن سُلَيْمَـٰنَ وَإِنَّهُۥ بِسْمِ ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ",
        "strategy": "exact"
      },
      {
        "ayah_key": "2:163",
        "chapter": 2,
        "verse": 163,
        "surah_name": "Al-Baqarah",
        "surah_name_arabic": "البقرة",
        "ayah_text": "وَإِلَـٰهُكُمْ إِلَـٰهٌ وَٰحِدٌ ۖ لَّآ إِلَـٰهَ إِلَّا هُوَ ٱلرَّحْمَـٰنُ ٱلرَّحِيمُ",
        "strategy": "exact"
      }
    ],
    "strategy_summary": {
      "exact": 5
    }
  }
}

Input

• query (string, required, 1–500 chars): Arabic search query. Diacritics and punctuation are stripped automatically.
• max_results (integer, optional, 1–100, default 20): Maximum number of matching ayahs to return.

Limits

• Query must be Arabic script — Latin-only queries return empty.
• Max 100 results per request.

Example User Prompts

• "Where does Allah say 'الرحمن الرحيم' in the Quran?"
• "Find the ayah that starts with 'الحمد لله'"
• "Show me ayahs containing 'نعبد'"

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ayah_search",
    "arguments": {
      "query": "الرحمن الرحيم",
      "max_results": 5
    }
  }
}

Example Result Shape

{
  "query": "الرحمن الرحيم",
  "total_results": 2,
  "results": [
    {
      "ayah_key": "1:1",
      "chapter": 1,
      "verse": 1,
      "surah_name": "Al-Fatihah",
      "surah_name_arabic": "الفاتحة",
      "ayah_text": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
      "strategy": "exact"
    }
  ],
  "strategy_summary": { "exact": 2 }
}

Chaining Patterns

ayah_search → user picks a result → ayah_tafsir / play_ayahs
search_ayahs_text → LLM picks keys → ayah_translation / ayah_tafsir