quran-mcp-server

Instructions

Implementation Reference

• src/handlers/resources.ts:179-211 (handler)

  The handler function that executes the tool logic for 'tafsir': validates input using tafsirSchema, calls tafsirsService.getTafsir(), formats response as MCP content.

  export async function handleTafsir(args: any) {
    try {
      // Validate arguments
      const validatedArgs = tafsirSchema.parse(args);
      
      // Call the service
      const result = await tafsirsService.getTafsir(validatedArgs);
      
      // Log the response in verbose mode
      verboseLog('response', {
        tool: 'tafsir',
        result
      });
      
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
    } catch (error) {
      verboseLog('error', {
        tool: 'tafsir',
        error: error instanceof Error ? error.message : String(error)
      });
      
      // Use the standardized error response utility
      const { createErrorResponse } = require('../utils/error-handler');
      return createErrorResponse(error, 'tafsir');
    }
  }

• src/schemas/tafsirs.ts:10-19 (schema)

  Zod schema defining the input parameters for the 'tafsir' tool.

  export const tafsirSchema = z.object({
    tafsir_id: z.string().describe("Tafsir id"),
    fields: z.string().optional().describe("Comma separated fields of tafsir"),
    chapter_number: z.string().optional().describe("Chapter number"),
    juz_number: z.string().optional().describe("Juz number"),
    page_number: z.string().optional().describe("Page number"),
    hizb_number: z.string().optional().describe("Hizb number"),
    rub_el_hizb_number: z.string().optional().describe("Rub el Hizb number"),
    verse_key: z.string().optional().describe("Verse key"),
  });

• src/server.ts:214-218 (registration)

  Registration of the 'tafsir' tool in the listTools response, including name, description, and input schema.

  {
    name: ApiTools.tafsir,
    description: "Get a single tafsir",
    inputSchema: zodToJsonSchema(tafsirsSchemas.tafsir),
  },

• src/server.ts:299-300 (registration)

  Dispatch case in CallToolRequest handler that routes 'tafsir' tool calls to handleTafsir function.

  case ApiTools.tafsir:
    return await handleTafsir(request.params.arguments);

• src/services/tafsirs-service.ts:179-220 (helper)

  Service method implementing the core API call to Quran.com for retrieving tafsir data, building URL and query params.

  async getTafsir(params: z.infer<typeof tafsirSchema>): Promise<TafsirResponse> {
    try {
      // Validate parameters
      const validatedParams = tafsirSchema.parse(params);
      
      // Build the URL based on the provided parameters
      let url = `${API_BASE_URL}/quran/tafsirs/${validatedParams.tafsir_id}`;
      
      // Prepare query parameters
      const queryParams: any = {};
      
      // Add optional parameters if provided
      if (validatedParams.fields) queryParams.fields = validatedParams.fields;
      if (validatedParams.chapter_number) queryParams.chapter_number = validatedParams.chapter_number;
      if (validatedParams.juz_number) queryParams.juz_number = validatedParams.juz_number;
      if (validatedParams.page_number) queryParams.page_number = validatedParams.page_number;
      if (validatedParams.hizb_number) queryParams.hizb_number = validatedParams.hizb_number;
      if (validatedParams.rub_el_hizb_number) queryParams.rub_el_hizb_number = validatedParams.rub_el_hizb_number;
      if (validatedParams.verse_key) queryParams.verse_key = validatedParams.verse_key;
      
      // Make request to Quran.com API
      const data = await makeApiRequest(url, queryParams);
      
      return {
        success: true,
        message: "tafsir executed successfully",
        data
      };
    } catch (error) {
      verboseLog('error', {
        method: 'getTafsir',
        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);
      }
      
      // Re-throw other errors
      throw error;
    }
  }