tafsirs
Access a comprehensive list of available Quranic tafsir explanations by specifying the language. Integrate with the Quran.com corpus via the official REST API v4 to enhance Quranic studies.
Instructions
Get list of available tafsirs
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Language |
Implementation Reference
- src/handlers/resources.ts:105-137 (handler)The handler function for the 'tafsirs' tool. It validates the input arguments using tafsirsSchema, calls tafsirsService.listTafsirs, logs the response, and returns the result as MCP-formatted content. Handles errors using createErrorResponse.export async function handleTafsirs(args: any) { try { // Validate arguments const validatedArgs = tafsirsSchema.parse(args); // Call the service const result = await tafsirsService.listTafsirs(validatedArgs); // Log the response in verbose mode verboseLog('response', { tool: 'tafsirs', result }); return { content: [ { type: "text", text: JSON.stringify(result, null, 2) } ] }; } catch (error) { verboseLog('error', { tool: 'tafsirs', error: error instanceof Error ? error.message : String(error) }); // Use the standardized error response utility const { createErrorResponse } = require('../utils/error-handler'); return createErrorResponse(error, 'tafsirs'); } }
- src/schemas/tafsirs.ts:24-26 (schema)Zod input schema for the 'tafsirs' tool, defining an optional 'language' parameter.export const tafsirsSchema = z.object({ language: z.string().optional().describe("Language"), });
- src/server.ts:295-296 (registration)Dispatch logic in the callTool handler that routes calls to the 'tafsirs' tool to the handleTafsirs function.case ApiTools.tafsirs: return await handleTafsirs(request.params.arguments);
- src/server.ts:204-208 (registration)Registration of the 'tafsirs' tool in the listTools response, including name, description, input schema, and examples.name: ApiTools.tafsirs, description: "Get list of available tafsirs", inputSchema: zodToJsonSchema(tafsirsSchemas.tafsirs), examples: toolExamples['tafsirs'], },
- The core service method listTafsirs in TafsirsService class. Fetches tafsirs list from Quran.com API (/resources/tafsirs) with caching, language param support, verbose logging, error handling, and fallback to mock data if API fails.async listTafsirs(params: z.infer<typeof tafsirsSchema>): Promise<TafsirsResponse> { try { // Validate parameters const validatedParams = tafsirsSchema.parse(params); // Check cache first const now = Date.now(); if (this.tafsirsCache && (now - this.cacheTimestamp < CACHE_DURATION_MS)) { verboseLog('response', { method: 'listTafsirs', source: 'cache', age: `${(now - this.cacheTimestamp) / 1000} seconds` }); return { success: true, message: "tafsirs executed successfully (from cache)", data: this.tafsirsCache }; } try { // Make request to Quran.com API const url = `${API_BASE_URL}/resources/tafsirs`; const response = await makeApiRequest(url, { language: validatedParams.language }); verboseLog('response', { method: 'listTafsirs', source: 'api', dataSize: JSON.stringify(response).length }); // Update cache this.tafsirsCache = response; this.cacheTimestamp = now; return { success: true, message: "tafsirs executed successfully", data: response }; } catch (axiosError) { verboseLog('error', { method: 'listTafsirs', error: axiosError instanceof Error ? axiosError.message : String(axiosError) }); // If the API call fails, return mock data verboseLog('response', { method: 'listTafsirs', source: 'mock', reason: 'API unavailable' }); const mockData = this.getTafsirsMockData(); return { success: true, message: "tafsirs executed with mock data (API unavailable)", data: mockData }; } } catch (error) { verboseLog('error', { method: 'listTafsirs', error: error instanceof Error ? error.message : String(error) }); if (error instanceof z.ZodError) { throw new ApiError(`Validation error: ${error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`, 400); } // Return mock data as a fallback for any error verboseLog('response', { method: 'listTafsirs', source: 'mock', reason: 'error occurred' }); const mockData = this.getTafsirsMockData(); return { success: true, message: "tafsirs executed with mock data (error occurred)", data: mockData }; } }