quran-mcp-server

Instructions

Implementation Reference

• src/handlers/chapters.ts:17-63 (handler)

  MCP tool handler for 'list-chapters': validates input args using Zod schema, delegates to chaptersService.listChapters, formats JSON response as text content, handles errors with verbose logging.

  export async function handleListChapters(args: any) {
    try {
      // Validate arguments
      const validatedArgs = listChaptersSchema.parse(args);
      
      // Call the service
      const result = await chaptersService.listChapters(validatedArgs);
      
      // Log the response in verbose mode
      verboseLog('response', {
        tool: 'list-chapters',
        result
      });
      
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
    } catch (error) {
      verboseLog('error', {
        tool: 'list-chapters',
        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:10-17 (schema)

  Zod input validation schema for 'list-chapters' tool defining the required 'language' parameter with constraints and description.

  export const listChaptersSchema = 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')"),
  });

• src/server.ts:124-128 (registration)

  Registration of 'list-chapters' tool in the MCP server's listTools handler: specifies name, description, input schema (converted from Zod), and usage examples.

    name: ApiTools.list_chapters,
    description: "List Chapters",
    inputSchema: zodToJsonSchema(chaptersSchemas.listChapters),
    examples: toolExamples['list-chapters'],
  },

• src/server.ts:257-258 (registration)

  Dispatch registration in MCP server's callTool handler: routes 'list-chapters' tool calls to the handleListChapters function.

  case ApiTools.list_chapters:
    return await handleListChapters(request.params.arguments);

• src/services/chapters-service.ts:39-143 (helper)

  Helper service method implementing core 'list-chapters' logic: parameter validation, caching, API call to Quran.com /chapters endpoint, data reduction, verbose logging, fallback to mock data on API failure or errors.

  async listChapters(params: z.infer<typeof listChaptersSchema>): Promise<ListChaptersResponse> {
    try {
      // Validate parameters
      const validatedParams = listChaptersSchema.parse(params);
      
      // Generate cache key based on parameters
      const cacheKey = `chapters_${validatedParams.language || 'en'}`;
      
      // Check cache first
      const cachedData = this.chaptersCache.get(cacheKey);
      if (cachedData) {
        verboseLog('response', {
          method: 'listChapters',
          source: 'cache',
          cacheSize: this.chaptersCache.size()
        });
        
        return {
          success: true,
          message: "list-chapters executed successfully (from cache)",
          data: cachedData
        };
      }
      
      try {
        // Make request to Quran.com API
        const url = `${API_BASE_URL}/chapters`;
        const response = await makeApiRequest(url, {
          language: validatedParams.language
        });
        
        // Process and reduce the data to only essential fields
        const reducedData = {
          chapters: response.chapters.map((chapter: any) => ({
            id: chapter.id,
            name_arabic: chapter.name_arabic,
            name_simple: chapter.name_simple,
            translated_name: { 
              name: chapter.translated_name?.name || "" 
            }
            // Only include essential fields
          }))
        };
        
        verboseLog('response', {
          method: 'listChapters',
          source: 'api',
          dataSize: JSON.stringify(reducedData).length
        });
        
        // Update cache with the new data
        this.chaptersCache.set(cacheKey, reducedData);
        
        return {
          success: true,
          message: "list-chapters executed successfully",
          data: reducedData
        };
      } catch (axiosError) {
        verboseLog('error', {
          method: 'listChapters',
          error: axiosError instanceof Error ? axiosError.message : String(axiosError)
        });
        
        // If the API call fails, return mock data
        verboseLog('response', {
          method: 'listChapters',
          source: 'mock',
          reason: 'API unavailable'
        });
        
        const mockData = this.getChaptersMockData();
        
        return {
          success: true,
          message: "list-chapters executed with mock data (API unavailable)",
          data: mockData
        };
      }
    } catch (error) {
      verboseLog('error', {
        method: 'listChapters',
        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: 'listChapters',
        source: 'mock',
        reason: 'error occurred'
      });
      
      const mockData = this.getChaptersMockData();
      
      return {
        success: true,
        message: "list-chapters executed with mock data (error occurred)",
        data: mockData
      };
    }
  }