Kroger MCP Server

Instructions

    Get an image for a specific product from the requested perspective.
    
    Use get_product_details first to see what perspectives are available (typically "front", "back", "left", "right").
    
    Args:
        product_id: The unique product identifier
        perspective: The image perspective to retrieve (default: "front")
        location_id: Store location ID (uses preferred if not provided)
    
    Returns:
        The product image from the requested perspective
    

Implementation Reference

• src/kroger_mcp/tools/product_tools.py:21-140 (handler)

  The handler function for the 'get_product_images' tool. It fetches product details from the Kroger API, finds the requested perspective image URL preferring larger sizes, downloads the image, and returns it as a FastMCP Image object. Handles errors and location preferences.

  @mcp.tool()
  async def get_product_images(
      product_id: str,
      perspective: str = "front",
      location_id: Optional[str] = None,
      ctx: Context = None
  ) -> Image:
      """
      Get an image for a specific product from the requested perspective.
      
      Use get_product_details first to see what perspectives are available (typically "front", "back", "left", "right").
      
      Args:
          product_id: The unique product identifier
          perspective: The image perspective to retrieve (default: "front")
          location_id: Store location ID (uses preferred if not provided)
      
      Returns:
          The product image from the requested perspective
      """
      # Use preferred location if none provided
      if not location_id:
          location_id = get_preferred_location_id()
          if not location_id:
              return {
                  "success": False,
                  "error": "No location_id provided and no preferred location set. Use set_preferred_location first."
              }
      
      if ctx:
          await ctx.info(f"Fetching images for product {product_id} at location {location_id}")
      
      client = get_client_credentials_client()
      
      try:
          # Get product details to extract image URLs
          product_details = client.product.get_product(
              product_id=product_id,
              location_id=location_id
          )
          
          if not product_details or "data" not in product_details:
              return {
                  "success": False,
                  "message": f"Product {product_id} not found"
              }
          
          product = product_details["data"]
          
          # Check if images are available
          if "images" not in product or not product["images"]:
              return {
                  "success": False,
                  "message": f"No images available for product {product_id}"
              }
          
          # Find the requested perspective image
          perspective_image = None
          available_perspectives = []
          
          for img_data in product["images"]:
              img_perspective = img_data.get("perspective", "unknown")
              available_perspectives.append(img_perspective)
              
              # Skip if not the requested perspective
              if img_perspective != perspective:
                  continue
                  
              if not img_data.get("sizes"):
                  continue
              
              # Find the best image size (prefer large, fallback to xlarge or other available)
              img_url = None
              size_preference = ["large", "xlarge", "medium", "small", "thumbnail"]
              
              # Create a map of available sizes for quick lookup
              available_sizes = {size.get("size"): size.get("url") for size in img_data.get("sizes", []) if size.get("size") and size.get("url")}
              
              # Select best size based on preference order
              for size in size_preference:
                  if size in available_sizes:
                      img_url = available_sizes[size]
                      break
              
              if img_url:
                  try:
                      if ctx:
                          await ctx.info(f"Downloading {perspective} image from {img_url}")
                      
                      # Download image
                      response = requests.get(img_url)
                      response.raise_for_status()
                      
                      # Create Image object
                      perspective_image = Image(
                          data=response.content,
                          format="jpeg"  # Kroger images are typically JPEG
                      )
                      break
                  except Exception as e:
                      if ctx:
                          await ctx.warning(f"Failed to download {perspective} image: {str(e)}")
          
          # If the requested perspective wasn't found
          if not perspective_image:
              available_str = ", ".join(available_perspectives) if available_perspectives else "none"
              return {
                  "success": False,
                  "message": f"No image found for perspective '{perspective}'. Available perspectives: {available_str}"
              }
          
          return perspective_image
      
      except Exception as e:
          if ctx:
              await ctx.error(f"Error getting product images: {str(e)}")
          return {
              "success": False,
              "error": str(e)
          }

• src/kroger_mcp/server.py:73-73 (registration)

  Registration of product tools (including get_product_images) by calling register_tools on the MCP server instance in the main server setup.

  product_tools.register_tools(mcp)

• src/kroger_mcp/tools/product_tools.py:18-18 (registration)

  The register_tools function in product_tools module that defines and registers the get_product_images tool using @mcp.tool() decorator.

  def register_tools(mcp):