verses-by_page_number
Retrieve Quranic verses by Madani Mushaf page number with optional translations, tafsirs, audio, and word details using the Quran MCP Server API.
Instructions
Get all verses of a specific Madani Mushaf page
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| audio | No | Id of recitation | |
| fields | No | Comma separated list of ayah fields | |
| language | No | Language to fetch word translation | |
| page | No | For paginating within the result | |
| page_number | Yes | Madani Mushaf page number (1-604) | |
| 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:69-117 (handler)The main handler function for the 'verses-by_page_number' tool. Validates input arguments using Zod schema, calls the verses service, logs the response/error, and returns formatted text content or error response./** * Handler for the verses-by_page_number tool */ export async function handleVersesByPageNumber(args: any) { try { // Validate arguments const validatedArgs = versesByPageNumberSchema.parse(args); // Call the service const result = await versesService.versesByPageNumber(validatedArgs); // Log the response in verbose mode verboseLog('response', { tool: 'verses-by_page_number', result }); return { content: [ { type: "text", text: JSON.stringify(result, null, 2) } ] }; } catch (error) { verboseLog('error', { tool: 'verses-by_page_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:36-42 (schema)Zod input schema for the tool, defining required 'page_number' and optional parameters like language, words, translations, audio, pagination, etc.* Schema for verses-by_page_number */ export const versesByPageNumberSchema = z.object({ page_number: z.string().describe("Madani Mushaf page number (1-604)"), ...commonVerseParams, ...paginationParams, });
- src/server.ts:147-150 (registration)Tool registration in the listTools request handler, specifying the tool name, description, and input schema (converted to JSON schema).name: ApiTools.verses_by_page_number, description: "Get all verses of a specific Madani Mushaf page", inputSchema: zodToJsonSchema(versesSchemas.versesByPageNumber), },
- src/server.ts:267-268 (registration)Handler dispatch in the callTool request handler, mapping the tool name to the execution of handleVersesByPageNumber.case ApiTools.verses_by_page_number: return await handleVersesByPageNumber(request.params.arguments);
- Supporting service method that performs the actual API call to Quran.com API endpoint /verses/by_page/{page_number}, handles validation, and returns structured response.* Get verses by page number * Get all verses of a specific Madani Mushaf page(1 to 604) * * @param {Object} params - The parameters for this operation * @returns {Promise<VersesByPageNumberResponse>} The operation result * @throws {ApiError} If the operation fails */ async versesByPageNumber(params: z.infer<typeof versesByPageNumberSchema>): Promise<VersesByPageNumberResponse> { try { // Validate parameters const validatedParams = versesByPageNumberSchema.parse(params); const url = `${API_BASE_URL}/verses/by_page/${validatedParams.page_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_page_number executed successfully", data }; } catch (error) { verboseLog('error', { method: 'versesByPageNumber', 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; } }