search

Instructions

Implementation Reference

• src/handlers/search.ts:13-58 (handler)

  Handler function for the 'search' tool. Validates input args using searchSchema, calls searchService.search(), logs verbose info, formats response as MCP content block, and handles Zod/validation errors.

  export async function handleSearch(args: any) {
    try {
      // Validate arguments
      const validatedArgs = searchSchema.parse(args);
      
      // Call the service
      const result = await searchService.search(validatedArgs);
      
      // Log the response in verbose mode
      verboseLog('response', {
        tool: 'search',
        result
      });
      
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
    } catch (error) {
      verboseLog('error', {
        tool: 'search',
        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/search.ts:10-15 (schema)

  Zod input schema for the search tool defining parameters: q (string, required), size/page/language (optional strings).

  export const searchSchema = z.object({
    q: z.string().describe("Search query, you can use *query* as well"),
    size: z.string().optional().describe("Results per page. *s* is also valid parameter."),
    page: z.string().optional().describe("Page number, well for pagination. You can use *p* as well"),
    language: z.string().optional().describe("ISO code of language, use this query params if you want to boost translations for specific language."),
  });

• src/server.ts:185-189 (registration)

  Tool registration in listTools handler: defines 'search' tool name (ApiTools.search), description, inputSchema from searchSchemas.search, and examples.

    name: ApiTools.search,
    description: "Search the Quran for specific terms",
    inputSchema: zodToJsonSchema(searchSchemas.search),
    examples: toolExamples['search'],
  },

• src/server.ts:285-286 (registration)

  Tool dispatch registration in callTool handler: switch case for 'search' that invokes handleSearch with arguments.

  case ApiTools.search:
    return await handleSearch(request.params.arguments);

• src/services/search-service.ts:24-57 (helper)

  Core search logic in SearchService.search(): validates params, constructs API URL, calls makeApiRequest to Quran.com /search endpoint with query params, returns formatted SearchResponse. Handles errors.

  async search(params: z.infer<typeof searchSchema>): Promise<SearchResponse> {
    try {
      // Validate parameters
      const validatedParams = searchSchema.parse(params);
      
      const url = `${API_BASE_URL}/search`;
      
      // Make request to Quran.com API
      const data = await makeApiRequest(url, {
        q: validatedParams.q,
        size: validatedParams.size,
        page: validatedParams.page,
        language: validatedParams.language
      });
      
      return {
        success: true,
        message: "search executed successfully",
        data
      };
    } catch (error) {
      verboseLog('error', {
        method: 'search',
        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;
    }
  }