tafsirs

Instructions

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'],
  },

• src/services/tafsirs-service.ts:38-127 (helper)

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