verses-by_verse_key
Retrieve Quran verses by their key, including translations, word details, tafsirs, and audio recitations, using the Quran MCP server for structured and detailed results.
Instructions
Get verse by key
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 | |
| tafsirs | No | Comma separated ids of tafsirs | |
| translation_fields | No | Comma separated list of translation fields | |
| translations | No | Comma separated ids of translations | |
| verse_key | Yes | Verse key (chapter:verse) | |
| word_fields | No | Comma separated list of word fields | |
| words | No | Include words of each ayah |
Implementation Reference
- src/handlers/verses.ts:273-322 (handler)MCP tool handler: validates input using schema, calls versesService, logs, returns JSON stringified result or error./** * Handler for the verses-by_verse_key tool */ export async function handleVersesByVerseKey(args: any) { try { // Validate arguments const validatedArgs = versesByVerseKeySchema.parse(args); // Call the service const result = await versesService.versesByVerseKey(validatedArgs); // Log the response in verbose mode verboseLog('response', { tool: 'verses-by_verse_key', result }); return { content: [ { type: "text", text: JSON.stringify(result, null, 2) } ] }; } catch (error) { verboseLog('error', { tool: 'verses-by_verse_key', 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:70-76 (schema)Zod input schema defining 'verse_key' required param and optional common verse params./** * Schema for verses-by_verse_key */ export const versesByVerseKeySchema = z.object({ verse_key: z.string().describe("Verse key (chapter:verse)"), ...commonVerseParams, });
- src/server.ts:166-171 (registration)Tool registration in MCP listTools handler: specifies name, description, inputSchema from Zod-to-JSON, and examples.{ name: ApiTools.verses_by_verse_key, description: "Get verse by key", inputSchema: zodToJsonSchema(versesSchemas.versesByVerseKey), examples: toolExamples['verses-by_verse_key'], },
- src/server.ts:275-276 (registration)Tool dispatch in MCP callTool handler: routes to the specific handler function.case ApiTools.verses_by_verse_key: return await handleVersesByVerseKey(request.params.arguments);
- Service helper: builds Quran.com API URL /verses/by_key/{verse_key}, makes request with params, returns structured response.* Get verse by key * Get a specific ayah with key. Key is combination of surah number and ayah number. * * @param {Object} params - The parameters for this operation * @returns {Promise<VersesByVerseKeyResponse>} The operation result * @throws {ApiError} If the operation fails */ async versesByVerseKey(params: z.infer<typeof versesByVerseKeySchema>): Promise<VersesByVerseKeyResponse> { try { // Validate parameters const validatedParams = versesByVerseKeySchema.parse(params); const url = `${API_BASE_URL}/verses/by_key/${validatedParams.verse_key}`; // 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 }); return { success: true, message: "verses-by_verse_key executed successfully", data }; } catch (error) { verboseLog('error', { method: 'versesByVerseKey', 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; } }