describe_image_from_file

Instructions

Best for: Local files when the server has filesystem access to the path.
Limitations: When using Docker, requires volume mapping (-v flag) to access host files.
Not recommended for: Images uploaded to chat or images with public URLs.

Args:
    filepath: Absolute path to the image file
    prompt: Optional prompt to guide the description

Returns:
    str: Detailed description of the image

Implementation Reference

• src/image_recognition_server/server.py:162-198 (handler)

  Main handler function for 'describe_image_from_file' tool. Registers the tool via @mcp.tool(), loads image from filepath, converts to base64, and delegates to internal describe_image processing logic.

  @mcp.tool()
  async def describe_image_from_file(
      filepath: str, prompt: str = "Please describe this image in detail."
  ) -> str:
      """Describe the contents of an image file using vision AI.
  
      Args:
          filepath: Path to the image file
          prompt: Optional prompt to use for the description.
  
      Returns:
          str: Detailed description of the image
      """
      try:
          logger.info(f"Processing image file: {filepath}")
  
          # Convert image to base64
          image_data, mime_type = image_to_base64(filepath)
          logger.info(f"Successfully converted image to base64. MIME type: {mime_type}")
          logger.debug(f"Base64 data length: {len(image_data)}")
  
          # Use describe_image tool
          result = await describe_image(image=image_data, prompt=prompt)
  
          if not result:
              raise ValueError("Received empty response from processing")
  
          return sanitize_output(result)
      except FileNotFoundError:
          logger.error(f"Image file not found: {filepath}")
          raise
      except ValueError as e:
          logger.error(f"Input error: {str(e)}")
          raise
      except Exception as e:
          logger.error(f"Error processing image file: {str(e)}", exc_info=True)
          raise

• src/image_recognition_server/utils/image.py:12-60 (helper)

  Supporting utility to convert an image file to base64-encoded string and MIME type, directly called by the describe_image_from_file handler.

  def image_to_base64(image_path: str) -> Tuple[str, str]:
      """Convert an image file to base64 string and detect its MIME type.
  
      Args:
          image_path: Path to the image file
  
      Returns:
          Tuple of (base64_string, mime_type)
  
      Raises:
          FileNotFoundError: If image file doesn't exist
          ValueError: If file is not a valid image
      """
      path = Path(image_path)
      if not path.exists():
          logger.error(f"Image file not found: {image_path}")
          raise FileNotFoundError(f"Image file not found: {image_path}")
  
      try:
          # Try to open and validate the image
          with Image.open(path) as img:
              # Get image format and convert to MIME type
              format_to_mime = {
                  "JPEG": "image/jpeg",
                  "PNG": "image/png",
                  "GIF": "image/gif",
                  "WEBP": "image/webp",
              }
              mime_type = format_to_mime.get(img.format, "application/octet-stream")
              logger.info(
                  f"Processing image: {image_path}, format: {img.format}, size: {img.size}"
              )
  
              # Convert to base64
              with path.open("rb") as f:
                  base64_data = base64.b64encode(f.read()).decode("utf-8")
                  logger.debug(f"Base64 data length: {len(base64_data)}")
  
              return base64_data, mime_type
  
      except UnidentifiedImageError as e:
          logger.error(f"Invalid image format: {str(e)}")
          raise ValueError(f"Invalid image format: {str(e)}")
      except OSError as e:
          logger.error(f"Failed to read image file: {str(e)}")
          raise ValueError(f"Failed to read image file: {str(e)}")
      except Exception as e:
          logger.error(f"Unexpected error processing image: {str(e)}", exc_info=True)
          raise ValueError(f"Failed to process image: {str(e)}")