chapter-reciters
Find chapter reciters for Quranic verses by specifying the desired language. Integrates with the Quran.com corpus REST API v4 for accurate and accessible recitation options.
Instructions
List of Chapter Reciters
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Name of reciters in specific language |
Implementation Reference
- src/handlers/resources.ts:213-248 (handler)The primary handler function that executes the 'chapter-reciters' tool logic. It validates the input arguments using the schema, calls the audio service, formats the response, and handles errors./** * Handler for the chapter-reciters tool */ export async function handleChapterReciters(args: any) { try { // Validate arguments const validatedArgs = chapterRecitersSchema.parse(args); // Call the service const result = await audioService.listChapterReciters(validatedArgs); // Log the response in verbose mode verboseLog('response', { tool: 'chapter-reciters', result }); return { content: [ { type: "text", text: JSON.stringify(result, null, 2) } ] }; } catch (error) { verboseLog('error', { tool: 'chapter-reciters', error: error instanceof Error ? error.message : String(error) }); // Use the standardized error response utility const { createErrorResponse } = require('../utils/error-handler'); return createErrorResponse(error, 'chapter-reciters'); } }
- src/schemas/audio.ts:44-50 (schema)Zod schema for validating input parameters to the 'chapter-reciters' tool, specifically an optional language parameter./** * Schema for chapter-reciters */ export const chapterRecitersSchema = z.object({ language: z.string().optional().describe("Name of reciters in specific language"), });
- src/server.ts:221-225 (registration)Registration of the 'chapter-reciters' tool in the MCP server's listTools response, defining its name, description, and input schema.name: ApiTools.chapter_reciters, description: "List of Chapter Reciters", inputSchema: zodToJsonSchema(audioSchemas.chapterReciters), }, {
- src/server.ts:303-304 (registration)Dispatch/registration of the handler function for the 'chapter-reciters' tool in the MCP callTool request handler switch statement.case ApiTools.chapter_reciters: return await handleChapterReciters(request.params.arguments);
- src/services/audio-service.ts:40-129 (helper)Core service method implementing the logic for fetching chapter reciters: API request, caching, fallback to mock data on errors.async listChapterReciters(params: z.infer<typeof chapterRecitersSchema>): Promise<ChapterRecitersResponse> { try { // Validate parameters const validatedParams = chapterRecitersSchema.parse(params); // Check cache first const now = Date.now(); if (this.chapterRecitersCache && (now - this.chapterRecitersCacheTimestamp < CACHE_DURATION_MS)) { verboseLog('response', { method: 'listChapterReciters', source: 'cache', age: `${(now - this.chapterRecitersCacheTimestamp) / 1000} seconds` }); return { success: true, message: "chapter-reciters executed successfully (from cache)", data: this.chapterRecitersCache }; } try { // Make request to Quran.com API const url = `${API_BASE_URL}/resources/chapter_reciters`; const response = await makeApiRequest(url, { language: validatedParams.language }); verboseLog('response', { method: 'listChapterReciters', source: 'api', dataSize: JSON.stringify(response).length }); // Update cache this.chapterRecitersCache = response; this.chapterRecitersCacheTimestamp = now; return { success: true, message: "chapter-reciters executed successfully", data: response }; } catch (axiosError) { verboseLog('error', { method: 'listChapterReciters', error: axiosError instanceof Error ? axiosError.message : String(axiosError) }); // If the API call fails, return mock data verboseLog('response', { method: 'listChapterReciters', source: 'mock', reason: 'API unavailable' }); const mockData = this.getChapterRecitersMockData(); return { success: true, message: "chapter-reciters executed with mock data (API unavailable)", data: mockData }; } } catch (error) { verboseLog('error', { method: 'listChapterReciters', 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: 'listChapterReciters', source: 'mock', reason: 'error occurred' }); const mockData = this.getChapterRecitersMockData(); return { success: true, message: "chapter-reciters executed with mock data (error occurred)", data: mockData }; } }