Superprecio MCP Server

Instructions

Implementation Reference

• src/tools/findNearbySupermarkets.ts:58-143 (handler)

  Main handler function for the 'find_nearby_supermarkets' tool. Calls the SuperPrecioApiClient, handles API response, errors, formats output with supermarket details, distances, and summaries.

  export async function executeFindNearbySupermarkets(
    client: SuperPrecioApiClient,
    args: { latitude: number; longitude: number; radiusKm?: number }
  ) {
    const response = await client.findNearbySupermarkets({
      lat: args.latitude,
      lng: args.longitude,
      radius: args.radiusKm || 5,
    });
  
    if (!response.success) {
      return {
        content: [
          {
            type: 'text',
            text: `Failed to find nearby supermarkets: ${response.message || 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  
    const locations = response.locations || [];
    const count = response.found || 0;
  
    if (count === 0) {
      return {
        content: [
          {
            type: 'text',
            text: `
  📍 No supermarkets found within ${response.radiusKm}km of your location.
  
  Search location:
    Latitude: ${response.searchLocation.latitude}
    Longitude: ${response.searchLocation.longitude}
  
  Try:
  - Increasing the search radius
  - Checking if your coordinates are correct
  - Moving to a different location
  `,
          },
        ],
      };
    }
  
    const summary = `
  📍 Nearby Supermarkets (${count} found)
  Search radius: ${response.radiusKm}km
  Location: ${response.searchLocation.latitude.toFixed(4)}, ${response.searchLocation.longitude.toFixed(4)}
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  
  ${locations
    .map((loc: any, i: number) => {
      return `
  ${i + 1}. ${loc.supermarketName} - ${loc.branchName}
     📏 Distance: ${loc.distance}km (${loc.distanceMeters}m)
     📍 Address: ${loc.address}, ${loc.city}
     ${loc.phone ? `📞 Phone: ${loc.phone}` : ''}
     ${loc.openingHours ? `🕒 Hours: ${loc.openingHours}` : ''}
     🗺️  Coordinates: ${loc.coordinates.latitude}, ${loc.coordinates.longitude}
  `;
    })
    .join('\n')}
  
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🚗 Closest supermarket: ${locations[0].supermarketName} (${locations[0].distance}km away)
  
  💡 Tip: After optimizing your shopping list, use this to find the nearest
     location of the best-priced supermarket!
  `;
  
    return {
      content: [
        {
          type: 'text',
          text: summary,
        },
        {
          type: 'text',
          text: JSON.stringify(response, null, 2),
        },
      ],
    };
  }

• src/tools/findNearbySupermarkets.ts:7-56 (schema)

  Tool schema definition including name, description, and input schema for latitude, longitude, and optional radius.

  export const findNearbySupermarketsTool = {
    name: 'find_nearby_supermarkets',
    description: `Find supermarkets near your current location using GPS coordinates.
  
  Discover which supermarkets are closest to you!
  
  Features:
  - Search by latitude and longitude
  - Customizable search radius (default: 5km)
  - Get distance in km and meters
  - See full addresses and contact info
  - Opening hours when available
  
  Perfect for:
  - Finding nearby stores after optimizing your shopping list
  - Planning your shopping route
  - Discovering new supermarkets in your area
  - Getting directions to the best-priced store
  
  Example coordinates for Buenos Aires city center:
  - Latitude: -34.6037
  - Longitude: -58.3816
  
  The tool uses the Haversine formula to calculate accurate distances.`,
    inputSchema: {
      type: 'object',
      properties: {
        latitude: {
          type: 'number',
          description: 'Latitude coordinate (-90 to 90)',
          minimum: -90,
          maximum: 90,
        },
        longitude: {
          type: 'number',
          description: 'Longitude coordinate (-180 to 180)',
          minimum: -180,
          maximum: 180,
        },
        radiusKm: {
          type: 'number',
          description: 'Search radius in kilometers (default: 5km)',
          minimum: 0.1,
          maximum: 50,
          default: 5,
        },
      },
      required: ['latitude', 'longitude'],
    },
  };

• src/index.ts:89-116 (registration)

  Registers the tool in the MCP server's listTools handler by including findNearbySupermarketsTool in the tools array.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        // V1 Tools
        searchProductsTool,
        searchByCodeTool,
        comparePriceTool,
        getBestDealsTool,
        sendNotificationTool,
        subscribeDeviceTool,
  
        // V2 Tools - Shopping Lists
        createShoppingListTool,
        addItemsToListTool,
        getShoppingListsTool,
        optimizeShoppingListTool,
        removeShoppingListTool,
  
        // V2 Tools - Price Alerts
        setPriceAlertTool,
        getMyAlertsTool,
        removePriceAlertTool,
  
        // V2 Tools - Location
        findNearbySupermarketsTool,
      ],
    };
  });

• src/index.ts:170-172 (registration)

  Dispatches execution of the tool in the MCP server's CallToolRequestSchema handler via switch case.

  case 'find_nearby_supermarkets':
    return await executeFindNearbySupermarkets(apiClient, args as any);

• src/client/superPrecioApi.ts:343-354 (helper)

  API client method that performs the HTTP GET request to '/api/locations/nearby' to fetch nearby supermarkets data.

  async findNearbySupermarkets(params: {
    lat: number;
    lng: number;
    radius?: number;
  }): Promise<any> {
    try {
      const response = await this.client.get('/api/locations/nearby', { params });
      return response.data;
    } catch (error) {
      throw this.handleError(error);
    }
  }