Bitrefill Search and Shop

Instructions

Implementation Reference

• src/handlers/tools.ts:41-61 (handler)

  The execution logic of the 'search' MCP tool handler, which invokes the SearchService and returns formatted results or error content.

  async (args) => {
    try {
      const searchResults = await SearchService.search(args.query, args);
      return {
        content: [
          { type: "text" as const, text: JSON.stringify(searchResults, null, 2) }
        ]
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({ error: errorMessage }, null, 2),
          },
        ],
        isError: true,
      };
    }
  }

• src/handlers/tools.ts:37-62 (registration)

  Registration of the 'search' tool on the MCP server, specifying name, description, input schema, and handler function.

  server.tool(
    "search",
    "Search for gift cards, esims, mobile topups and more. It's suggested to use the `categories` tool before searching for products, to have a better understanding of what's available.",
    SearchOptions,
    async (args) => {
      try {
        const searchResults = await SearchService.search(args.query, args);
        return {
          content: [
            { type: "text" as const, text: JSON.stringify(searchResults, null, 2) }
          ]
        };
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : String(error);
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({ error: errorMessage }, null, 2),
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/schemas/search.ts:9-24 (schema)

  Input schema (SearchOptions) for the 'search' tool, defining parameters like query, country, limit, etc., using Zod.

  export const SearchOptions = {
    query: z.string().describe("Search query (e.g., 'Amazon', 'Netflix', 'AT&T' or '*' for all the available products)"),
    country: z.string().optional().describe("Country code (e.g., 'US', 'IT', 'GB')"),
    language: z.string().optional().describe("Language code for results (e.g., 'en')"),
    limit: z.number().optional().describe("Maximum number of results to return"),
    skip: z.number().optional().describe("Number of results to skip (for pagination)"),
    category: z.string().optional().describe("Filter by category (e.g., 'gaming', 'entertainment')"),
    beta_flags: z.string().optional().describe("Beta feature flags"),
    cart: z.string().optional().describe("Cart identifier"),
    do_recommend: z.number().optional().describe("Enable recommendations"),
    rec: z.number().optional().describe("Recommendation parameter"),
    sec: z.number().optional().describe("Security parameter"),
    col: z.number().optional().describe("Column layout parameter"),
    prefcc: z.number().optional().describe("Preferred country code parameter"),
    src: z.string().optional().describe("Source of the request"),
  };

• src/services/search.ts:19-28 (helper)

  Helper method in SearchService that validates options and delegates to publicApiClient.search for the actual API call.

  public static async search(
    query: string,
    options: Partial<SearchOptionsType> = {}
  ): Promise<SearchResults> {
    // Validate options
    const validatedOptions = SearchOptionsSchema.parse(options);
    
    // Use the public API client to perform the search
    return publicApiClient.search(query, validatedOptions);
  }