quran-mcp-server

Instructions

Implementation Reference

• src/handlers/resources.ts:66-99 (handler)

  The primary handler function for executing the 'translation-info' tool. It validates the input arguments using the translationInfoSchema, calls the translationsService to retrieve the translation information, logs the response or error, and returns the result as a formatted text content block.

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

• src/schemas/translations.ts:22-26 (schema)

  Zod schema used for input validation of the 'translation-info' tool, requiring a 'translation_id' string parameter.

   * Schema for translation-info
   */
  export const translationInfoSchema = z.object({
    translation_id: z.string().describe("Translation id"),
  });

• src/server.ts:198-201 (registration)

  Registration of the 'translation-info' tool in the MCP server's tool list, specifying name, description, and input schema.

    name: ApiTools.translation_info,
    description: "Get information of a specific translation",
    inputSchema: zodToJsonSchema(translationsSchemas.translationInfo),
  },

• src/server.ts:290-292 (registration)

  Dispatch logic in the tool call handler that routes 'translation-info' calls to the handleTranslationInfo function.

    return await handleTranslations(request.params.arguments);
  case ApiTools.translation_info:
    return await handleTranslationInfo(request.params.arguments);

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

  Service class method that performs the actual API request to Quran.com for translation info based on translation_id, handles errors, and returns structured response.

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