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;
  }