quran-mcp-server

Instructions

Implementation Reference

• src/handlers/chapters.ts:68-113 (handler)

  The main handler function for the GET-chapter tool. It validates input arguments using getChapterSchema, calls the chaptersService.getChapter method, logs the response, and formats the result as MCP content or handles errors appropriately.

  export async function handleGetChapter(args: any) {
    try {
      // Validate arguments
      const validatedArgs = getChapterSchema.parse(args);
      
      // Call the service
      const result = await chaptersService.getChapter(validatedArgs);
      
      // Log the response in verbose mode
      verboseLog('response', {
        tool: 'GET-chapter',
        result
      });
      
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
    } catch (error) {
      verboseLog('error', {
        tool: 'GET-chapter',
        error: error instanceof Error ? error.message : String(error)
      });
      
      if (error instanceof z.ZodError) {
        return {
          content: [{ 
            type: "text", 
            text: `Validation error: ${error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`
          }],
          isError: true,
        };
      }
      
      return {
        content: [{ 
          type: "text", 
          text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
        }],
        isError: true,
      };
    }

• src/schemas/chapters.ts:22-40 (schema)

  Zod schema for validating input parameters to the GET-chapter tool: language (string) and optional id (string or number, 1-114).

  export const getChapterSchema = z.object({
    language: z.string()
      .trim()
      .min(2, "Language code must be at least 2 characters")
      .max(10, "Language code must not exceed 10 characters")
      .regex(/^[a-zA-Z-]+$/, "Language code must contain only letters and hyphens")
      .describe("Parameter language (e.g., 'en', 'ar', 'fr-CA')"),
    id: z.union([
      z.string()
        .trim()
        .regex(/^\d+$/, "Chapter ID must be a positive integer")
        .transform(Number),
      z.number()
        .int("Chapter ID must be an integer")
        .positive("Chapter ID must be positive")
    ])
      .optional()
      .describe("Chapter ID (1-114)"),
  });

• src/server.ts:130-134 (registration)

  Registration of the GET-chapter tool in the MCP server's list of available tools, including name, description, input schema (from chaptersSchemas.getChapter), and examples.

    name: ApiTools.GET_chapter,
    description: "Get Chapter",
    inputSchema: zodToJsonSchema(chaptersSchemas.getChapter),
    examples: toolExamples['GET-chapter'],
  },

• src/server.ts:259-260 (registration)

  Dispatch/registration in the tool call handler switch statement, routing calls to 'GET-chapter' to the handleGetChapter function.

  case ApiTools.GET_chapter:
    return await handleGetChapter(request.params.arguments);

• src/services/chapters-service.ts:155-188 (helper)

  Supporting service method getChapter that performs the actual API request to Quran.com API endpoint /chapters/{id}, handles validation, defaults to chapter 1, and returns structured response.

  async getChapter(params: z.infer<typeof getChapterSchema>): Promise<GetChapterResponse> {
    try {
      // Validate parameters
      const validatedParams = getChapterSchema.parse(params);
      
      // Default to chapter 1 if no ID is provided
      const chapterId = params.id || '1';
      
      const url = `${API_BASE_URL}/chapters/${chapterId}`;
      
      // Make request to Quran.com API
      const data = await makeApiRequest(url, {
        language: validatedParams.language
      });
      
      return {
        success: true,
        message: "GET-chapter executed successfully",
        data
      };
    } catch (error) {
      verboseLog('error', {
        method: 'getChapter',
        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;
    }
  }