quran-mcp-server

Instructions

Implementation Reference

• src/handlers/resources.ts:250-282 (handler)

  MCP handler function for the 'recitation-styles' tool. Validates input (none), calls audioService.listRecitationStyles(), logs response/error, returns formatted JSON content or error.
  /** * Handler for the recitation-styles tool */ export async function handleRecitationStyles(args: any) { try { // Call the service const result = await audioService.listRecitationStyles(); // Log the response in verbose mode verboseLog('response', { tool: 'recitation-styles', result }); return { content: [ { type: "text", text: JSON.stringify(result, null, 2) } ] }; } catch (error) { verboseLog('error', { tool: 'recitation-styles', error: error instanceof Error ? error.message : String(error) }); // Use the standardized error response utility const { createErrorResponse } = require('../utils/error-handler'); return createErrorResponse(error, 'recitation-styles'); } }
• src/schemas/audio.ts:58-62 (schema)

  Zod input schema for recitation-styles tool, empty object as no parameters are required.
  /** * Schema for recitation-styles */ export const recitationStylesSchema = z.object({});
• src/server.ts:226-229 (registration)

  Tool registration in listTools handler: defines name 'recitation-styles', description, and inputSchema from audioSchemas.recitationStyles.
  name: ApiTools.recitation_styles, description: "Get the available recitation styles", inputSchema: zodToJsonSchema(audioSchemas.recitationStyles), },
• src/server.ts:305-306 (registration)

  Tool dispatch registration in callTool handler switch: routes 'recitation-styles' calls to handleRecitationStyles function.
  case ApiTools.recitation_styles: return await handleRecitationStyles(request.params.arguments);
• src/services/audio-service.ts:138-218 (helper)

  Core implementation in AudioService: fetches recitation styles from Quran.com API (/resources/recitation_styles), uses caching, falls back to mock data on API failure or errors, returns structured response.
  async listRecitationStyles(): Promise<RecitationStylesResponse> { try { // Check cache first const now = Date.now(); if (this.recitationStylesCache && (now - this.recitationStylesCacheTimestamp < CACHE_DURATION_MS)) { verboseLog('response', { method: 'listRecitationStyles', source: 'cache', age: `${(now - this.recitationStylesCacheTimestamp) / 1000} seconds` }); return { success: true, message: "recitation-styles executed successfully (from cache)", data: this.recitationStylesCache }; } try { // Make request to Quran.com API const url = `${API_BASE_URL}/resources/recitation_styles`; const response = await makeApiRequest(url); verboseLog('response', { method: 'listRecitationStyles', source: 'api', dataSize: JSON.stringify(response).length }); // Update cache this.recitationStylesCache = response; this.recitationStylesCacheTimestamp = now; return { success: true, message: "recitation-styles executed successfully", data: response }; } catch (axiosError) { verboseLog('error', { method: 'listRecitationStyles', error: axiosError instanceof Error ? axiosError.message : String(axiosError) }); // If the API call fails, return mock data verboseLog('response', { method: 'listRecitationStyles', source: 'mock', reason: 'API unavailable' }); const mockData = this.getRecitationStylesMockData(); return { success: true, message: "recitation-styles executed with mock data (API unavailable)", data: mockData }; } } catch (error) { verboseLog('error', { method: 'listRecitationStyles', error: error instanceof Error ? error.message : String(error) }); // Return mock data as a fallback for any error verboseLog('response', { method: 'listRecitationStyles', source: 'mock', reason: 'error occurred' }); const mockData = this.getRecitationStylesMockData(); return { success: true, message: "recitation-styles executed with mock data (error occurred)", data: mockData }; } }