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
      };
    }
  }