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',
    };
  });

src/shared/tools-definition.ts:81-106 (schema)

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;
}

Quran MCP Server