get_recitation_url
Retrieve MP3 audio URLs for Quran verse recitations by specifying surah, ayah, and reciter to enable listening to specific verses.
Instructions
Get audio recitation URL for a specific Quran verse. Returns MP3 URL for listening to the verse.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| surah | Yes | Surah number (1-114) | |
| ayah | Yes | Ayah (verse) number | |
| reciter | No | Reciter name (default: Maher_AlMuaiqly_64kbps). Use list_reciters to see all options. | Maher_AlMuaiqly_64kbps |
Implementation Reference
- src/tools/recitation.ts:21-70 (handler)Core handler function that validates surah, ayah, reciter; uses caching; constructs MP3 recitation URL.
export async function getRecitationURL( surah: number, ayah: number, reciterSlug: string = 'Maher_AlMuaiqly_64kbps' ): Promise<RecitationInfo> { // Validate inputs if (!isValidSurah(surah)) { throw new QuranMCPError( `Invalid surah number: ${surah}. Must be between 1 and 114.`, 'INVALID_SURAH' ); } if (!isValidAyah(surah, ayah)) { const surahInfo = getSurahInfo(surah); throw new QuranMCPError( `Invalid ayah number: ${ayah}. Surah ${surah} has ${surahInfo?.ayahs} ayahs.`, 'INVALID_AYAH' ); } // Validate reciter const reciter = RECITERS.find(r => r.slug === reciterSlug); if (!reciter) { throw new QuranMCPError( `Unknown reciter: ${reciterSlug}. Available reciters: ${RECITERS.map(r => r.slug).join(', ')}`, 'INVALID_RECITER' ); } // Create cache key const cacheKey = `recitation:${reciterSlug}:${surah}:${ayah}`; // Try to get from cache or generate return recitationCacheService.getOrSet(cacheKey, async () => { // Format numbers with leading zeros const surahFormatted = formatSurahNumber(surah); const ayahFormatted = formatAyahNumber(ayah); // Build URL const url = `${API_ENDPOINTS.RECITATION}/${reciterSlug}/${surahFormatted}${ayahFormatted}.mp3`; return { surah, ayah, reciter: reciter.name, url, format: 'mp3', }; }); - Tool definition including name, description, and input schema for validation.
{ name: 'get_recitation_url', description: 'Get audio recitation URL for a specific Quran verse. Returns MP3 URL for listening to the verse.', inputSchema: { type: 'object', properties: { surah: { type: 'number', description: 'Surah number (1-114)', minimum: 1, maximum: 114, }, ayah: { type: 'number', description: 'Ayah (verse) number', minimum: 1, }, reciter: { type: 'string', description: 'Reciter name (default: Maher_AlMuaiqly_64kbps). Use list_reciters to see all options.', default: 'Maher_AlMuaiqly_64kbps', }, }, required: ['surah', 'ayah'], }, }, - src/shared/tool-executor.ts:63-67 (registration)Dispatches the tool call in the executeTool switch statement by invoking the handler.
case 'get_recitation_url': { const { surah, ayah, reciter = 'Maher_AlMuaiqly_64kbps' } = args; result = await getRecitationURL(surah, ayah, reciter); break; }