quran-mcp-server

Instructions

Implementation Reference

• src/handlers/resources.ts:142-173 (handler)

  The handler function that executes the tafsir-info tool: validates input using tafsirInfoSchema, calls tafsirsService.getTafsirInfo, logs, and returns formatted text response.

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

• src/schemas/tafsirs.ts:31-33 (schema)

  Zod schema defining the input parameters for the tafsir-info tool (requires tafsir_id).

  export const tafsirInfoSchema = z.object({
    tafsir_id: z.string().describe("Tafsir id"),
  });

• src/server.ts:209-213 (registration)

  Tool registration in the listTools response: defines name, description, and inputSchema for tafsir-info.

  {
    name: ApiTools.tafsir_info,
    description: "Get the information of a specific tafsir",
    inputSchema: zodToJsonSchema(tafsirsSchemas.tafsirInfo),
  },

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

  Tool call routing in the switch statement: dispatches tafsir-info calls to handleTafsirInfo handler.

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

• src/services/tafsirs-service.ts:138-166 (helper)

  Service method that performs the core API request to fetch tafsir info from Quran.com API.

  async getTafsirInfo(params: z.infer<typeof tafsirInfoSchema>): Promise<TafsirInfoResponse> {
    try {
      // Validate parameters
      const validatedParams = tafsirInfoSchema.parse(params);
      
      const url = `${API_BASE_URL}/resources/tafsirs/${validatedParams.tafsir_id}/info`;
      
      // Make request to Quran.com API
      const data = await makeApiRequest(url);
      
      return {
        success: true,
        message: "tafsir-info executed successfully",
        data
      };
    } catch (error) {
      verboseLog('error', {
        method: 'getTafsirInfo',
        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;
    }
  }