get_tafsir
Retrieve scholarly commentary and explanations for specific Quran verses to understand their context and interpretation. Provides access to Tafsir sources for deeper insight into Islamic texts.
Instructions
Get Tafsir (commentary/explanation) for a specific Quran verse. Provides scholarly interpretation and context.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| surah | Yes | Surah number (1-114) | |
| ayah | Yes | Ayah (verse) number | |
| tafsir | No | Tafsir source (default: en-tafisr-ibn-kathir). Use list_tafsir_sources to see all options. | en-tafisr-ibn-kathir |
Implementation Reference
- src/tools/tafsir.ts:20-77 (handler)The core handler function that implements the get_tafsir tool logic: input validation, caching, API fetching, and error handling.
export async function getTafsir( surah: number, ayah: number, tafsirSlug: string = 'en-tafisr-ibn-kathir' ): Promise<TafsirResponse> { // 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' ); } // Check if tafsir source exists const tafsirSource = TAFSIR_SOURCES.find(t => t.slug === tafsirSlug); if (!tafsirSource) { throw new QuranMCPError( `Unknown tafsir source: ${tafsirSlug}. Available sources: ${TAFSIR_SOURCES.map(t => t.slug).join(', ')}`, 'INVALID_TAFSIR_SOURCE' ); } // Create cache key const cacheKey = `tafsir:${tafsirSlug}:${surah}:${ayah}`; // Try to get from cache or fetch return tafsirCacheService.getOrSet(cacheKey, async () => { const url = `${API_ENDPOINTS.TAFSIR}/${tafsirSlug}/${surah}/${ayah}.json`; try { const data = await fetchJSON<any>(url); return { surah, ayah, text: data.text || data.tafsir || '', tafsir_name: tafsirSource.name, language: tafsirSource.language, }; } catch (error) { if (error instanceof QuranMCPError) { throw error; } throw new QuranMCPError( `Failed to fetch tafsir: ${(error as Error).message}`, 'TAFSIR_FETCH_ERROR' ); } }); } - src/shared/tools-definition.ts:35-60 (registration)MCP tool registration definition including name, description, and input schema for get_tafsir.
{ name: 'get_tafsir', description: 'Get Tafsir (commentary/explanation) for a specific Quran verse. Provides scholarly interpretation and context.', 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, }, tafsir: { type: 'string', description: 'Tafsir source (default: en-tafisr-ibn-kathir). Use list_tafsir_sources to see all options.', default: 'en-tafisr-ibn-kathir', }, }, required: ['surah', 'ayah'], }, }, - src/types/index.ts:115-119 (schema)TypeScript interface defining the input parameters for the getTafsir function.
export interface GetTafsirParams { surah: number; ayah: number; tafsir?: string; } - src/shared/tool-executor.ts:51-55 (handler)Tool dispatcher case that invokes the getTafsir handler with parsed arguments.
case 'get_tafsir': { const { surah, ayah, tafsir = 'en-tafisr-ibn-kathir' } = args; result = await getTafsir(surah, ayah, tafsir); break; }