verses-by_juz_number
Retrieve Quranic verses by Juz number, including translations, tafsirs, audio, and word details, using the Quran MCP server for precise and structured access to scripture content.
Instructions
Get verses by Juz number
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| audio | No | Id of recitation | |
| fields | No | Comma separated list of ayah fields | |
| juz_number | Yes | Juz number (1-30) | |
| 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:120-169 (handler)Main handler function that parses arguments with Zod schema, invokes the verses service, logs the operation, and returns formatted MCP content or error response./** * Handler for the verses-by_juz_number tool */ export async function handleVersesByJuzNumber(args: any) { try { // Validate arguments const validatedArgs = versesByJuzNumberSchema.parse(args); // Call the service const result = await versesService.versesByJuzNumber(validatedArgs); // Log the response in verbose mode verboseLog('response', { tool: 'verses-by_juz_number', result }); return { content: [ { type: "text", text: JSON.stringify(result, null, 2) } ] }; } catch (error) { verboseLog('error', { tool: 'verses-by_juz_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:44-51 (schema)Zod input schema defining parameters for the tool: juz_number (required), optional common verse params (language, words, etc.) and pagination./** * Schema for verses-by_juz_number */ export const versesByJuzNumberSchema = z.object({ juz_number: z.string().describe("Juz number (1-30)"), ...commonVerseParams, ...paginationParams, });
- src/server.ts:152-155 (registration)MCP tool registration in listTools handler: defines name, description, and converts Zod schema to JSON schema for input validation.name: ApiTools.verses_by_juz_number, description: "Get verses by Juz number", inputSchema: zodToJsonSchema(versesSchemas.versesByJuzNumber), },
- src/server.ts:269-270 (registration)Dispatch registration in CallToolRequestSchema handler: maps tool name to the specific handler function call.case ApiTools.verses_by_juz_number: return await handleVersesByJuzNumber(request.params.arguments);
- Core service logic: validates params, builds Quran.com API URL (/verses/by_juz/{juz_number}), makes request with optional params, wraps response in success object.async versesByJuzNumber(params: z.infer<typeof versesByJuzNumberSchema>): Promise<VersesByJuzNumberResponse> { try { // Validate parameters const validatedParams = versesByJuzNumberSchema.parse(params); const url = `${API_BASE_URL}/verses/by_juz/${validatedParams.juz_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_juz_number executed successfully", data }; } catch (error) { verboseLog('error', { method: 'versesByJuzNumber', 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; } }