search_locations
Find nearby Kroger store locations by entering a zip code within a specified radius. Customize results with filters for distance, number of stores, and chain name.
Instructions
Search for Kroger store locations near a zip code.
Args:
zip_code: Zip code to search near (uses environment default if not provided)
radius_in_miles: Search radius in miles (1-100)
limit: Number of results to return (1-200)
chain: Filter by specific chain name
Returns:
Dictionary containing location search results
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chain | No | ||
| limit | No | Number of results to return (1-200) | |
| radius_in_miles | No | Search radius in miles (1-100) | |
| zip_code | No |
Implementation Reference
- The handler function for the 'search_locations' MCP tool. It handles input parameters (with Pydantic validation), searches Kroger locations using the SDK client, formats the results, and returns structured data or error responses.@mcp.tool() async def search_locations( zip_code: Optional[str] = None, radius_in_miles: int = Field(default=10, ge=1, le=100, description="Search radius in miles (1-100)"), limit: int = Field(default=10, ge=1, le=200, description="Number of results to return (1-200)"), chain: Optional[str] = None, ctx: Context = None ) -> Dict[str, Any]: """ Search for Kroger store locations near a zip code. Args: zip_code: Zip code to search near (uses environment default if not provided) radius_in_miles: Search radius in miles (1-100) limit: Number of results to return (1-200) chain: Filter by specific chain name Returns: Dictionary containing location search results """ if ctx: await ctx.info(f"Searching for Kroger locations near {zip_code or 'default zip code'}") if not zip_code: # If Claude isn't provided with a zip code, he will sometimes generate one. # Which is why get_user_zip_code() is provided as a tool, to ensure Claude uses the # default zip code provided in the env. zip_code = get_default_zip_code() client = get_client_credentials_client() try: locations = client.location.search_locations( zip_code=zip_code, radius_in_miles=radius_in_miles, limit=limit, chain=chain ) if not locations or "data" not in locations or not locations["data"]: return { "success": False, "message": f"No locations found near zip code {zip_code}", "data": [] } # Format location data for easier consumption formatted_locations = [] for loc in locations["data"]: address = loc.get("address", {}) formatted_loc = { "location_id": loc.get("locationId"), "name": loc.get("name"), "chain": loc.get("chain"), "phone": loc.get("phone"), "address": { "street": address.get("addressLine1", ""), "city": address.get("city", ""), "state": address.get("state", ""), "zip_code": address.get("zipCode", "") }, "full_address": f"{address.get('addressLine1', '')}, {address.get('city', '')}, {address.get('state', '')} {address.get('zipCode', '')}", "coordinates": loc.get("geolocation", {}), "departments": [dept.get("name") for dept in loc.get("departments", [])], "department_count": len(loc.get("departments", [])) } # Add hours info if available if "hours" in loc and "monday" in loc["hours"]: monday = loc["hours"]["monday"] if monday.get("open24", False): formatted_loc["hours_monday"] = "Open 24 hours" elif "open" in monday and "close" in monday: formatted_loc["hours_monday"] = f"{monday['open']} - {monday['close']}" else: formatted_loc["hours_monday"] = "Hours not available" formatted_locations.append(formatted_loc) if ctx: await ctx.info(f"Found {len(formatted_locations)} locations") return { "success": True, "search_params": { "zip_code": zip_code, "radius_miles": radius_in_miles, "limit": limit, "chain": chain }, "count": len(formatted_locations), "data": formatted_locations } except Exception as e: if ctx: await ctx.error(f"Error searching locations: {str(e)}") return { "success": False, "error": str(e), "data": [] }
- src/kroger_mcp/server.py:72-72 (registration)Registers the location_tools module (including search_locations) with the FastMCP server instance.location_tools.register_tools(mcp)
- src/kroger_mcp/server.py:23-23 (registration)Imports the location_tools module containing the search_locations tool implementation.from .tools import location_tools