Quran MCP Server

Instructions

Implementation Reference

• src/tools/quran.ts:154-196 (handler)

  Main handler function that implements the get_full_surah tool logic. Fetches all verses of the specified surah, optionally including translation, using cached API fetches and helper functions.

  export async function getFullSurah(
    surah: number,
    includeTranslation: boolean = false,
    translationSlug: string = 'en.asad'
  ): Promise<QuranVerse[]> {
    if (!isValidSurah(surah)) {
      throw new QuranMCPError(
        `Invalid surah number: ${surah}. Must be between 1 and 114.`,
        'INVALID_SURAH'
      );
    }
  
    const surahInfo = getSurahInfo(surah);
    if (!surahInfo) {
      throw new QuranMCPError(
        `Could not find info for surah ${surah}`,
        'SURAH_INFO_NOT_FOUND'
      );
    }
  
    const verses: QuranVerse[] = [];
  
    for (let ayah = 1; ayah <= surahInfo.ayahs; ayah++) {
      try {
        if (includeTranslation) {
          const verse = await getQuranVerse(surah, ayah, translationSlug);
          verses.push({
            surah,
            ayah,
            text: verse.arabic.text,
            translation: verse.translation.text,
          });
        } else {
          const verse = await getQuranArabic(surah, ayah);
          verses.push(verse);
        }
      } catch (error) {
        console.error(`Failed to fetch verse ${surah}:${ayah}:`, error);
      }
    }
  
    return verses;
  }

• src/shared/tools-definition.ts:107-132 (schema)

  Tool schema definition including input validation, properties, and description for get_full_surah.

  {
    name: 'get_full_surah',
    description: 'Get all verses of a complete Surah (chapter). Can include translations.',
    inputSchema: {
      type: 'object',
      properties: {
        surah: {
          type: 'number',
          description: 'Surah number (1-114)',
          minimum: 1,
          maximum: 114,
        },
        include_translation: {
          type: 'boolean',
          description: 'Whether to include English translation (default: false)',
          default: false,
        },
        translation: {
          type: 'string',
          description: 'Translation to use if include_translation is true (default: en.asad)',
          default: 'en.asad',
        },
      },
      required: ['surah'],
    },
  },

• src/shared/tool-executor.ts:69-73 (registration)

  Registration in the tool executor switch statement that maps the tool name to the handler function call.

  case 'get_full_surah': {
    const { surah, include_translation = false, translation = 'en.asad' } = args;
    result = await getFullSurah(surah, include_translation, translation);
    break;
  }

• src/shared/tool-executor.ts:10-14 (registration)

  Import statement registering the getFullSurah handler for use in the executor.

    getFullSurah,
    getQuranVerse,
    getRandomVerse,
    listTranslations
  } from '../tools/quran.js';