amazon_bestsellers

Instructions

Implementation Reference

• src/tools/amazon-bestsellers/amazon-bestsellers-tool.ts:18-61 (handler)

  The AmazonBestsellersTool class that registers and implements the 'amazon_bestsellers' MCP tool. The handler function builds scraping params with the AMAZON_BESTSELLERS target, calls sapiClient.scrape(), and returns the data as text content.

  export class AmazonBestsellersTool extends Tool {
    toolset = TOOLSET.ECOMMERCE;
  
    transformResponse = ({ data }: { data: object }) => {
      return { data: JSON.stringify(data) };
    };
  
    register = ({ server, sapiClient, auth }: ToolRegistrationArgs) => {
      server.registerTool(
        'amazon_bestsellers',
        {
          description: 'Scrape Amazon Bestsellers list with automatic parsing',
          inputSchema: {
            query: z.string().describe('Amazon category (e.g., "mobile-apps", "electronics")'),
            domain: zodDomain,
            deviceType: zodDeviceType,
            pageFrom: zodPageFrom,
          },
          annotations: {
            readOnlyHint: true,
            openWorldHint: true,
          },
        },
        async (scrapingParams: ScrapingMCPParams, extra: ProgressExtra) => {
          const params = {
            ...scrapingParams,
            target: SCRAPER_API_TARGETS.AMAZON_BESTSELLERS,
            parse: true,
          } satisfies ScraperAPIParams;
  
          const { data } = await sapiClient.scrape<object>({ auth, scrapingParams: params, extra });
  
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(data),
              },
            ],
          };
        }
      );
    };
  }

• src/tools/amazon-bestsellers/amazon-bestsellers-tool.ts:30-35 (schema)

  Input schema for the amazon_bestsellers tool: query (required string), domain (optional string), deviceType (optional), pageFrom (optional number).

  inputSchema: {
    query: z.string().describe('Amazon category (e.g., "mobile-apps", "electronics")'),
    domain: zodDomain,
    deviceType: zodDeviceType,
    pageFrom: zodPageFrom,
  },

• src/tools/amazon-bestsellers/amazon-bestsellers-tool.ts:8-16 (schema)

  Zod schema definitions for optional inputs: domain (Amazon domain) and pageFrom (pagination start page).

  const zodDomain = z
    .string()
    .describe('Amazon domain (e.g., amazon.com, amazon.co.uk)')
    .optional();
  
  const zodPageFrom = z
    .number()
    .describe('Starting page number for pagination')
    .optional();

• src/server/sapi-base-server.ts:113-117 (registration)

  Registration: AmazonBestsellersTool is instantiated in the allTools array (line 78) and registered via registerAllTools() or registerTools() which calls tool.register() on it.

  registerAllTools() {
    for (const tool of ScraperAPIBaseServer.allTools) {
      tool.register({ server: this.server, sapiClient: this.sapiClient, auth: this.auth });
    }
  }

• src/constants.ts:21-21 (helper)

  The SCRAPER_API_TARGETS.AMAZON_BESTSELLERS constant used as the target value when making the scraping API call.

  AMAZON_BESTSELLERS = 'amazon_bestsellers',