get_tafsir
Retrieve scholarly commentary and interpretation for specific Quran verses to understand their meaning and context.
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)Core handler function that validates surah/ayah/tafsirSlug parameters, checks tafsir source validity, uses cache, fetches from API endpoint, and returns TafsirResponse.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 defining the 'get_tafsir' tool name, description, and input schema for validation.{ 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/shared/tool-executor.ts:51-55 (handler)Tool dispatcher switch case that extracts parameters and invokes the getTafsir handler function.case 'get_tafsir': { const { surah, ayah, tafsir = 'en-tafisr-ibn-kathir' } = args; result = await getTafsir(surah, ayah, tafsir); break; }
- src/types/index.ts:115-119 (schema)TypeScript interface defining input parameters for get_tafsir tool.export interface GetTafsirParams { surah: number; ayah: number; tafsir?: string; }
- src/tools/tafsir.ts:82-89 (helper)Helper function to list available tafsir sources, referenced in tool description for valid tafsir slugs.export function listTafsirSources() { return TAFSIR_SOURCES.map(source => ({ slug: source.slug, name: source.name, language: source.language, author: source.author, })); }