verses-by_rub_el_hizb_number

Instructions

Implementation Reference

• src/handlers/verses.ts:222-271 (handler)

  The MCP tool handler function that validates the input arguments using Zod, invokes the verses service method, logs the execution, and formats the response as a JSON text block or error message.

  /**
   * Handler for the verses-by_rub_el_hizb_number tool
   */
  export async function handleVersesByRubElHizbNumber(args: any) {
    try {
      // Validate arguments
      const validatedArgs = versesByRubElHizbNumberSchema.parse(args);
      
      // Call the service
      const result = await versesService.versesByRubElHizbNumber(validatedArgs);
      
      // Log the response in verbose mode
      verboseLog('response', {
        tool: 'verses-by_rub_el_hizb_number',
        result
      });
      
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
    } catch (error) {
      verboseLog('error', {
        tool: 'verses-by_rub_el_hizb_number',
        error: error instanceof Error ? error.message : String(error)
      });
      
      if (error instanceof z.ZodError) {
        return {
          content: [{ 
            type: "text", 
            text: `Validation error: ${error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`
          }],
          isError: true,
        };
      }
      
      return {
        content: [{ 
          type: "text", 
          text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
        }],
        isError: true,
      };
    }
  }

• src/schemas/verses.ts:62-68 (schema)

  Zod schema defining the input parameters for the tool: required 'rub_el_hizb_number' string (1-240) and optional common verse parameters like language, words, translations, etc.

  /**
   * Schema for verses-by_rub_el_hizb_number
   */
  export const versesByRubElHizbNumberSchema = z.object({
    rub_el_hizb_number: z.string().describe("Rub el Hizb number (1-240)"),
    ...commonVerseParams,
  });

• src/server.ts:162-165 (registration)

  MCP tool registration in the listTools response: defines the tool name, description, and converts the Zod input schema to JSON schema.

    name: ApiTools.verses_by_rub_el_hizb_number,
    description: "Get verses by Rub el Hizb number",
    inputSchema: zodToJsonSchema(versesSchemas.versesByRubElHizbNumber),
  },

• src/server.ts:273-274 (registration)

  Dispatch registration in the callTool request handler switch statement: maps the tool name to the execution of the handler function.

  case ApiTools.verses_by_rub_el_hizb_number:
    return await handleVersesByRubElHizbNumber(request.params.arguments);

• src/services/verses-service.ts:230-274 (helper)

  Supporting service method that constructs the Quran.com API URL (/verses/by_rub/{rub_el_hizb_number}), appends query parameters, makes the HTTP request via makeApiRequest, and returns structured success response or throws errors.

   * Get verses by rub el hizb number
   * Get all verses of a specific Rub el Hizb number(1-240).
   * 
   * @param {Object} params - The parameters for this operation
   * @returns {Promise<VersesByRubElHizbNumberResponse>} The operation result
   * @throws {ApiError} If the operation fails
   */
  async versesByRubElHizbNumber(params: z.infer<typeof versesByRubElHizbNumberSchema>): Promise<VersesByRubElHizbNumberResponse> {
    try {
      // Validate parameters
      const validatedParams = versesByRubElHizbNumberSchema.parse(params);
      
      const url = `${API_BASE_URL}/verses/by_rub/${validatedParams.rub_el_hizb_number}`;
      
      // Make request to Quran.com API
      const data = await makeApiRequest(url, {
        language: validatedParams.language,
        words: validatedParams.words,
        translations: validatedParams.translations,
        audio: validatedParams.audio,
        tafsirs: validatedParams.tafsirs,
        word_fields: validatedParams.word_fields,
        translation_fields: validatedParams.translation_fields,
        fields: validatedParams.fields
      });
      
      return {
        success: true,
        message: "verses-by_rub_el_hizb_number executed successfully",
        data
      };
    } catch (error) {
      verboseLog('error', {
        method: 'versesByRubElHizbNumber',
        error: error instanceof Error ? error.message : String(error)
      });
      
      if (error instanceof z.ZodError) {
        throw new ApiError(`Validation error: ${error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`, 400);
      }
      
      // Re-throw other errors
      throw error;
    }
  }