play_ayahs

Fetch Quranic ayah audio playlist data.

Use This When

• The user asks to play/listen to ayahs.
• The user needs reciter-specific audio URLs for ayah ranges.

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": "Play Surah Al-Fatiha recited by Mahmoud Khalil Al Husary.",
  "request": {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "play_ayahs",
      "arguments": {
        "queries": [
          {
            "start_ayah": "1:1",
            "end_ayah": "1:7",
            "reciter_id": 20
          }
        ]
      }
    }
  },
  "response": {
    "items": [
      {
        "ayah_key": "1:1",
        "audio_url": "https://audio-cdn.tarteel.ai/quran/husary/001001.mp3",
        "reciter_id": 20,
        "reciter_name": "Mahmoud Khalil Al Husary - Murattal",
        "chapter_id": 1,
        "chapter_name": "Al-Fatihah",
        "chapter_name_arabic": "الفاتحة"
      },
      {
        "ayah_key": "1:2",
        "audio_url": "https://audio-cdn.tarteel.ai/quran/husary/001002.mp3",
        "reciter_id": 20,
        "reciter_name": "Mahmoud Khalil Al Husary - Murattal",
        "chapter_id": 1,
        "chapter_name": "Al-Fatihah",
        "chapter_name_arabic": "الفاتحة"
      },
      {
        "ayah_key": "1:3",
        "audio_url": "https://audio-cdn.tarteel.ai/quran/husary/001003.mp3",
        "reciter_id": 20,
        "reciter_name": "Mahmoud Khalil Al Husary - Murattal",
        "chapter_id": 1,
        "chapter_name": "Al-Fatihah",
        "chapter_name_arabic": "الفاتحة"
      },
      {
        "ayah_key": "1:4",
        "audio_url": "https://audio-cdn.tarteel.ai/quran/husary/001004.mp3",
        "reciter_id": 20,
        "reciter_name": "Mahmoud Khalil Al Husary - Murattal",
        "chapter_id": 1,
        "chapter_name": "Al-Fatihah",
        "chapter_name_arabic": "الفاتحة"
      },
      {
        "ayah_key": "1:5",
        "audio_url": "https://audio-cdn.tarteel.ai/quran/husary/001005.mp3",
        "reciter_id": 20,
        "reciter_name": "Mahmoud Khalil Al Husary - Murattal",
        "chapter_id": 1,
        "chapter_name": "Al-Fatihah",
        "chapter_name_arabic": "الفاتحة"
      },
      {
        "ayah_key": "1:6",
        "audio_url": "https://audio-cdn.tarteel.ai/quran/husary/001006.mp3",
        "reciter_id": 20,
        "reciter_name": "Mahmoud Khalil Al Husary - Murattal",
        "chapter_id": 1,
        "chapter_name": "Al-Fatihah",
        "chapter_name_arabic": "الفاتحة"
      },
      {
        "ayah_key": "1:7",
        "audio_url": "https://audio-cdn.tarteel.ai/quran/husary/001007.mp3",
        "reciter_id": 20,
        "reciter_name": "Mahmoud Khalil Al Husary - Murattal",
        "chapter_id": 1,
        "chapter_name": "Al-Fatihah",
        "chapter_name_arabic": "الفاتحة"
      }
    ],
    "total_ayahs": 7,
    "unique_reciters": [20],
    "queries": [
      {
        "start_ayah": "1:1",
        "end_ayah": "1:7",
        "reciter_id": 20
      }
    ]
  }
}

Input

• queries (array, required, min 1, max 50): List of audio queries.
• default_reciter_id (number, optional, default 20): Reciter ID used when a query omits reciter_id.

Each query:

• start_ayah (string, required): Start ayah key in "surah:ayah" format (for example "1:1").
• end_ayah (string, optional): End ayah key in "surah:ayah" format. Omit to request only start_ayah.
• reciter_id (number, optional): Per-query reciter override.

Available Reciters

Current reciter IDs and names:

Reciter IDs and names

• 5: Hani ar-Rifai - Murattal
• 8: Mohamed Siddiq al Minshawi - Mujawwad
• 11: Mohamed al-Tablawi
• 13: Maher Al Muaiqly - Murattal
• 14: Abdul Baset Abdul Samad - Mujawwad
• 15: Abdul Baset Abdul Samad - Murattal
• 16: Abd ur Rahman as Sudais - Murattal
• 17: Abu Bakr al-Shatri - Murattal
• 18: Mishari Rashid al Afasy - Murattal
• 19: Saad al Ghamdi - Murattal
• 20: Mahmoud Khalil Al Husary - Murattal
• 21: Mahmoud Khalil Al-Husary - Mujawwad
• 22: Mahmoud Khalil Al-Husary - Muallim
• 23: Khalifa Al Tunaiji - Murattal
• 24: Mohamed Siddiq al-Minshawi - Murattal
• 25: Saud Al-Shuraim - Murattal
• 26: Yasser Al-Dosari - Murattal
• 42: Ahmad Alnufais

Limits

• Maximum 50 queries per call
• Maximum 200 ayahs per request

Example User Prompts

• "Play Surah Al-Fatiha (1:1-1:7)."
• "Fetch audio for ayah 2:255 with reciter 20."
• "Create a playlist for 18:1 to 18:5."

Example Request

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "play_ayahs",
    "arguments": {
      "default_reciter_id": 20,
      "queries": [
        {
          "start_ayah": "1:1",
          "end_ayah": "1:5",
          "reciter_id": 20
        }
      ]
    }
  }
}