Quran MCP Server

Instructions

Implementation Reference

• src/tools/quran.ts:212-235 (handler)

  The core handler function that selects a random surah and ayah, fetches the Arabic text, and optionally the translation using helper functions.

  export async function getRandomVerse(
    includeTranslation: boolean = true,
    translationSlug: string = 'en.asad'
  ): Promise<{ arabic: QuranVerse; translation?: QuranVerse; surahInfo: any }> {
    // Pick random surah
    const randomSurah = Math.floor(Math.random() * 114) + 1;
    const surahInfo = getSurahInfo(randomSurah);
    
    if (!surahInfo) {
      throw new QuranMCPError('Failed to get random verse', 'RANDOM_VERSE_ERROR');
    }
  
    // Pick random ayah from that surah
    const randomAyah = Math.floor(Math.random() * surahInfo.ayahs) + 1;
  
    const arabic = await getQuranArabic(randomSurah, randomAyah);
    
    if (includeTranslation) {
      const translation = await getQuranTranslation(randomSurah, randomAyah, translationSlug);
      return { arabic, translation, surahInfo };
    }
  
    return { arabic, surahInfo };
  }

• src/shared/tools-definition.ts:133-151 (schema)

  MCP tool definition including name, description, and input schema for validation.

  {
    name: 'get_random_verse',
    description: 'Get a random verse from the Quran. Great for daily inspiration!',
    inputSchema: {
      type: 'object',
      properties: {
        include_translation: {
          type: 'boolean',
          description: 'Whether to include English translation (default: true)',
          default: true,
        },
        translation: {
          type: 'string',
          description: 'Translation to use (default: en.asad)',
          default: 'en.asad',
        },
      },
    },
  },

• src/shared/tool-executor.ts:75-79 (registration)

  Registration in the tool dispatcher switch statement that maps the tool name to the handler execution.

  case 'get_random_verse': {
    const { include_translation = true, translation = 'en.asad' } = args;
    result = await getRandomVerse(include_translation, translation);
    break;
  }