Quran MCP Server

Instructions

Implementation Reference

• src/tools/hadith.ts:111-128 (handler)

  Core handler function that implements get_random_hadith logic: selects random collection if unspecified, picks random hadith number, and fetches using getHadith.

  export async function getRandomHadith(collection?: string): Promise<HadithResponse> {
    // If no collection specified, pick a random one
    const selectedCollection = collection ||
      HADITH_COLLECTIONS[Math.floor(Math.random() * HADITH_COLLECTIONS.length)].slug;
  
    const collectionInfo = HADITH_COLLECTIONS.find(c => c.slug === selectedCollection);
    if (!collectionInfo) {
      throw new QuranMCPError(
        `Unknown hadith collection: ${selectedCollection}`,
        'INVALID_COLLECTION'
      );
    }
  
    // Get random hadith number
    const randomNumber = Math.floor(Math.random() * collectionInfo.totalHadiths) + 1;
  
    return getHadith(selectedCollection, randomNumber);
  }

• src/shared/tools-definition.ts:152-165 (schema)

  Tool schema definition including name, description, and input validation schema.

  {
    name: 'get_random_hadith',
    description: 'Get a random Hadith from a collection. Great for daily inspiration!',
    inputSchema: {
      type: 'object',
      properties: {
        collection: {
          type: 'string',
          description: 'Hadith collection (optional). If not specified, picks from any collection.',
          enum: ['bukhari', 'muslim', 'abudawud', 'tirmidhi', 'nasai', 'ibnmajah'],
        },
      },
    },
  },

• src/shared/tool-executor.ts:81-84 (registration)

  Tool registration in the central switch dispatcher that maps tool name to handler execution.

  case 'get_random_hadith': {
    const { collection } = args;
    result = await getRandomHadith(collection);
    break;