Superprecio MCP Server

Instructions

Implementation Reference

• src/tools/searchByCode.ts:31-83 (handler)

  The executeSearchByCode function implements the core logic of the 'search_by_code' tool. It validates input, calls the SuperPrecio API client's searchByCode method, processes the response data from multiple supermarkets, and returns a formatted JSON result indicating availability and pricing.

  export async function executeSearchByCode(
    client: SuperPrecioApiClient,
    args: { code: string }
  ) {
    if (!args) {
      throw new Error('Missing required arguments');
    }
  
    const { code } = args;
  
    const response = await client.searchByCode(code);
  
    // Format response
    const results = {
      summary: {
        barcode: code,
        totalSupermarkets: response.columns,
        foundIn: response.allData.length,
      },
      availability: response.allData.map((marketProducts, idx) => {
        const market = response.markets[idx];
        if (!marketProducts || marketProducts.length === 0) {
          return {
            supermarket: market ? market.name : 'Unknown',
            available: false,
          };
        }
  
        const product = marketProducts[0];
        return {
          supermarket: market ? market.name : 'Unknown',
          logo: market ? market.logo : '',
          available: true,
          product: {
            name: product.desc,
            price: product.price,
            image: product.img,
            link: product.link,
            code: product.code,
          },
        };
      }),
    };
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(results, null, 2),
        },
      ],
    };
  }

• src/tools/searchByCode.ts:7-29 (schema)

  Defines the 'search_by_code' tool metadata, including name, detailed description, and input schema specifying the required 'code' parameter as a string.

  export const searchByCodeTool = {
    name: 'search_by_code',
    description: `Search for a specific product by its EAN/barcode across all supermarkets.
  
  This tool is perfect for:
  - Finding exact product matches
  - Scanning barcodes
  - Price checking specific items
  - Verifying product availability
  
  The barcode/EAN search will find the exact same product across different stores,
  making it ideal for precise price comparisons.`,
    inputSchema: {
      type: 'object',
      properties: {
        code: {
          type: 'string',
          description: 'Product EAN/barcode (numeric code, usually 13 digits)',
        },
      },
      required: ['code'],
    },
  };

• src/index.ts:128-129 (registration)

  In the MCP server's CallToolRequestSchema handler, dispatches execution of 'search_by_code' to the executeSearchByCode function.

  case 'search_by_code':
    return await executeSearchByCode(apiClient, args as any);

• src/index.ts:93-94 (registration)

  Registers the searchByCodeTool in the list of available tools returned by ListToolsRequestSchema handler.

  searchProductsTool,
  searchByCodeTool,

• src/client/superPrecioApi.ts:97-106 (helper)

  SuperPrecioApiClient method that sends HTTP POST request to '/api/productsByCode' endpoint with the code and returns the search response.

  async searchByCode(code: string): Promise<SearchResponse> {
    try {
      const response = await this.client.post<SearchResponse>('/api/productsByCode', {
        search: code,
      });
      return response.data;
    } catch (error) {
      throw this.handleError(error);
    }
  }