Quran MCP Server

Instructions

Implementation Reference

• src/tools/hadith.ts:14-95 (handler)

  Core implementation of the get_hadith tool: validates inputs, checks cache, fetches from API (English then Arabic fallback), parses response, and returns structured HadithResponse.
  export async function getHadith( collection: string, hadithNumber: number ): Promise<HadithResponse> { // Validate collection const collectionInfo = HADITH_COLLECTIONS.find(c => c.slug === collection); if (!collectionInfo) { throw new QuranMCPError( `Unknown hadith collection: ${collection}. Available collections: ${HADITH_COLLECTIONS.map(c => c.slug).join(', ')}`, 'INVALID_COLLECTION' ); } // Validate hadith number if (hadithNumber < 1 || hadithNumber > collectionInfo.totalHadiths) { throw new QuranMCPError( `Invalid hadith number: ${hadithNumber}. ${collectionInfo.name} has ${collectionInfo.totalHadiths} hadiths.`, 'INVALID_HADITH_NUMBER' ); } // Create cache key const cacheKey = `hadith:${collection}:${hadithNumber}`; // Try to get from cache or fetch return hadithCacheService.getOrSet(cacheKey, async () => { // Try English first, fallback to Arabic const endpoints = [ `${API_ENDPOINTS.HADITH}/eng-${collection}/${hadithNumber}.json`, `${API_ENDPOINTS.HADITH}/ara-${collection}/${hadithNumber}.json`, ]; let lastError: Error | null = null; for (const url of endpoints) { try { const data = await fetchJSON<any>(url); // Handle the actual API structure: { metadata: {...}, hadiths: [{text: "..."}] } let text = ''; let book = undefined; let chapter = undefined; let grade = undefined; let narrator = undefined; if (data.hadiths && Array.isArray(data.hadiths) && data.hadiths.length > 0) { // Find the hadith with matching number const hadith = data.hadiths.find((h: any) => h.hadithnumber === hadithNumber) || data.hadiths[0]; text = hadith.text || ''; book = hadith.reference?.book; chapter = data.metadata?.section?.[book]; grade = hadith.grades?.[0]; } else { // Fallback to old structure text = data.text || data.hadith || ''; book = data.book; chapter = data.chapter || data.chapterName; grade = data.grade; narrator = data.narrator; } return { hadithNumber, collection: collectionInfo.name, book, chapter, text, grade, narrator, }; } catch (error) { lastError = error as Error; continue; } } throw new QuranMCPError( `Failed to fetch hadith: ${lastError?.message}`, 'HADITH_FETCH_ERROR' ); }); }
• src/shared/tools-definition.ts:62-80 (registration)

  MCP tool registration defining the name, description, and input schema for the get_hadith tool.
  name: 'get_hadith', description: 'Get a specific Hadith from a collection. Hadiths are sayings and actions of Prophet Muhammad (peace be upon him).', inputSchema: { type: 'object', properties: { collection: { type: 'string', description: 'Hadith collection name. Options: bukhari, muslim, abudawud, tirmidhi, nasai, ibnmajah', enum: ['bukhari', 'muslim', 'abudawud', 'tirmidhi', 'nasai', 'ibnmajah'], }, hadith_number: { type: 'number', description: 'Hadith number within the collection', minimum: 1, }, }, required: ['collection', 'hadith_number'], }, },
• src/types/index.ts:121-124 (schema)

  TypeScript interface for input parameters of the get_hadith tool.
  export interface GetHadithParams { collection: string; hadithNumber: number; }
• src/types/index.ts:40-48 (schema)

  TypeScript interface defining the output structure returned by get_hadith handler.
  export interface HadithResponse { hadithNumber: number; collection: string; book?: string; chapter?: string; text: string; grade?: string; narrator?: string; }
• src/shared/tool-executor.ts:57-61 (helper)

  Dispatch logic in shared tool executor that invokes the getHadith handler for the 'get_hadith' tool name.
  case 'get_hadith': { const { collection, hadith_number } = args; result = await getHadith(collection, hadith_number); break; }