verses-by_hizb_number

Retrieve Quran verses by Hizb number, including translations, audio, tafsirs, and word details for in-depth study and analysis.

Instructions

Get verses by Hizb number

Input Schema

TableJSON Schema

Name	Required	Description
`audio`	No	Id of recitation
`fields`	No	Comma separated list of ayah fields
`hizb_number`	Yes	Hizb number (1-60)
`language`	No	Language to fetch word translation
`page`	No	For paginating within the result
`per_page`	No	Records per api call
`tafsirs`	No	Comma separated ids of tafsirs
`translation_fields`	No	Comma separated list of translation fields
`translations`	No	Comma separated ids of translations
`word_fields`	No	Comma separated list of word fields
`words`	No	Include words of each ayah

Implementation Reference

src/handlers/verses.ts:171-219 (handler)

The MCP tool handler function that validates input using the schema, calls the verses service, logs the operation, and returns the result as JSON or error response.

/**
 * Handler for the verses-by_hizb_number tool
 */
export async function handleVersesByHizbNumber(args: any) {
  try {
    // Validate arguments
    const validatedArgs = versesByHizbNumberSchema.parse(args);
    
    // Call the service
    const result = await versesService.versesByHizbNumber(validatedArgs);
    
    // Log the response in verbose mode
    verboseLog('response', {
      tool: 'verses-by_hizb_number',
      result
    });
    
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2)
        }
      ]
    };
  } catch (error) {
    verboseLog('error', {
      tool: 'verses-by_hizb_number',
      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/verses.ts:53-60 (schema)

Zod schema defining the input parameters for the verses-by_hizb_number tool, including hizb_number and common verse/pagination options.

/**
 * Schema for verses-by_hizb_number
 */
export const versesByHizbNumberSchema = z.object({
  hizb_number: z.string().describe("Hizb number (1-60)"),
  ...commonVerseParams,
  ...paginationParams,
});

src/server.ts:157-160 (registration)

Tool metadata registration in the listTools handler: name, description, and input schema for discovery by MCP clients.

  name: ApiTools.verses_by_hizb_number,
  description: "Get verses by Hizb number",
  inputSchema: zodToJsonSchema(versesSchemas.versesByHizbNumber),
},

src/server.ts:271-272 (registration)
Tool execution registration in the callTool handler switch: maps tool name to handler invocation.
```
case ApiTools.verses_by_hizb_number:
  return await handleVersesByHizbNumber(request.params.arguments);
```

src/services/verses-service.ts:181-227 (helper)

Supporting service method that performs the actual API call to Quran.com for verses by hizb number, handles validation and error throwing.

 * Get verses by hizb number
 * Get all verses from a specific Hizb(1-60).
 * 
 * @param {Object} params - The parameters for this operation
 * @returns {Promise<VersesByHizbNumberResponse>} The operation result
 * @throws {ApiError} If the operation fails
 */
async versesByHizbNumber(params: z.infer<typeof versesByHizbNumberSchema>): Promise<VersesByHizbNumberResponse> {
  try {
    // Validate parameters
    const validatedParams = versesByHizbNumberSchema.parse(params);
    
    const url = `${API_BASE_URL}/verses/by_hizb/${validatedParams.hizb_number}`;
    
    // Make request to Quran.com API
    const data = await makeApiRequest(url, {
      language: validatedParams.language,
      words: validatedParams.words,
      translations: validatedParams.translations,
      audio: validatedParams.audio,
      tafsirs: validatedParams.tafsirs,
      word_fields: validatedParams.word_fields,
      translation_fields: validatedParams.translation_fields,
      fields: validatedParams.fields,
      page: validatedParams.page,
      per_page: validatedParams.per_page
    });
    
    return {
      success: true,
      message: "verses-by_hizb_number executed successfully",
      data
    };
  } catch (error) {
    verboseLog('error', {
      method: 'versesByHizbNumber',
      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;
  }
}

quran-mcp-server