verses-by_chapter_number
Retrieve Quranic verses by specifying chapter numbers, with options for translations, audio, tafsirs, and word details. Simplify access to Quran text and interpretations in your preferred language.
Instructions
Get verses by Chapter / Surah number
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| audio | No | Id of recitation | |
| chapter_number | Yes | Chapter number (1-114) | |
| fields | No | Comma separated list of ayah fields | |
| 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:21-67 (handler)The MCP tool handler function `handleVersesByChapterNumber` that validates input arguments using Zod schema, calls the versesService, logs the response or error, and returns MCP-compatible content blocks.export async function handleVersesByChapterNumber(args: any) { try { // Validate arguments const validatedArgs = versesByChapterNumberSchema.parse(args); // Call the service const result = await versesService.versesByChapterNumber(validatedArgs); // Log the response in verbose mode verboseLog('response', { tool: 'verses-by_chapter_number', result }); return { content: [ { type: "text", text: JSON.stringify(result, null, 2) } ] }; } catch (error) { verboseLog('error', { tool: 'verses-by_chapter_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:27-33 (schema)Zod schema defining the input parameters for the tool, including required 'chapter_number' and optional common verse parameters (language, words, translations, etc.) and pagination.* Schema for verses-by_chapter_number */ export const versesByChapterNumberSchema = z.object({ chapter_number: z.string().describe("Chapter number (1-114)"), ...commonVerseParams, ...paginationParams, });
- src/server.ts:141-144 (registration)Registration of the tool in the server's listTools response, providing name, description, input schema, and usage examples.name: ApiTools.verses_by_chapter_number, description: "Get verses by Chapter / Surah number", inputSchema: zodToJsonSchema(versesSchemas.versesByChapterNumber), examples: toolExamples['verses-by_chapter_number'],
- src/server.ts:265-266 (registration)Dispatch registration in the server's callTool handler switch statement, routing calls to the specific handler function.case ApiTools.verses_by_chapter_number: return await handleVersesByChapterNumber(request.params.arguments);
- src/services/verses-service.ts:41-80 (helper)Core service logic that constructs the Quran.com API endpoint URL, passes parameters to makeApiRequest, and wraps the response in a structured format with success message.async versesByChapterNumber(params: z.infer<typeof versesByChapterNumberSchema>): Promise<VersesByChapterNumberResponse> { try { // Validate parameters const validatedParams = versesByChapterNumberSchema.parse(params); const url = `${API_BASE_URL}/verses/by_chapter/${validatedParams.chapter_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_chapter_number executed successfully", data }; } catch (error) { verboseLog('error', { method: 'versesByChapterNumber', 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; } }