quran-mcp-server

Instructions

Implementation Reference

• src/handlers/juzs.ts:13-58 (handler)

  Main handler function for the 'juzs' tool. Validates input using juzsSchema, calls juzsService.getJuzs, formats response as MCP content or error.

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

  Zod input schema for the juzs tool, defined as an empty object indicating no required parameters.

  export const juzsSchema = z.object({});

• src/server.ts:178-183 (registration)

  Tool registration in the listTools response, defining name, description, input schema, and examples for 'juzs'.

  {
    name: ApiTools.juzs,
    description: "Get list of all juzs",
    inputSchema: zodToJsonSchema(juzsSchemas.juzs),
    examples: toolExamples['juzs'],
  },

• src/server.ts:280-282 (registration)

  Dispatch/handling of 'juzs' tool call in the CallToolRequestSchema switch statement, invoking handleJuzs.

  // Juzs-related tools
  case ApiTools.juzs:
    return await handleJuzs(request.params.arguments);

• src/services/juzs-service.ts:25-52 (helper)

  Service method that fetches juzs data from Quran.com API endpoint '/juzs', handles validation and errors, called by the handler.

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