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 | Default |
|---|---|---|---|
| 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);
- 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; } }