read_pdf

Instructions

Implementation Reference

• main.py:103-126 (handler)

  The handler function for the 'read_pdf' tool. It uses the Lizeur class to perform OCR on the PDF file at the given absolute path and returns a structured dictionary with the OCR results including pages and metadata. The @mcp.tool() decorator registers it as an MCP tool.

  @mcp.tool()
  def read_pdf(absolute_path: str) -> dict:
      """Read a PDF document and return the complete OCRResponse as a dictionary.
  
      Returns the full OCR response including all pages, not just the first page.
      The response includes pages with markdown content, bounding boxes, and other OCR metadata.
      """
      ocr_response = Lizeur().read_document(Path(absolute_path))
      if ocr_response is None:
          return {"error": "Failed to process document"}
  
      response_data = ocr_response.model_dump()
      return {
          "status": "success",
          "document_path": absolute_path,
          "total_pages": len(response_data.get("pages", [])),
          "pages": response_data.get("pages", []),
          "metadata": {
              k: v
              for k, v in response_data.items()
              if k != "pages" and k != "model_dump_json"
          },
      }

• main.py:33-64 (helper)

  Core helper method in Lizeur class that handles reading and caching of OCR results for documents, used by the read_pdf tool.

  def read_document(self, path: Path) -> OCRResponse | None:
      """Read a document and return the OCRResponse."""
      logging.info(f"read_document: Reading document {path.name}")
      # Check if the document is already cached
      cached_document_path = self.cache_path / path.name
      if cached_document_path.exists():
          logging.info(f"read_document: Document {path.name} is already cached.")
          try:
              with open(cached_document_path, "r") as f:
                  cached_json = f.read()
                  # Parse JSON and reconstruct OCRResponse
                  cached_data = json.loads(cached_json)
                  return OCRResponse.model_validate(cached_data)
          except (json.JSONDecodeError, ValueError) as e:
              logging.warning(f"Failed to load cached document {path.name}: {e}")
              # Remove corrupted cache file
              cached_document_path.unlink(missing_ok=True)
  
      # OCR the document
      ocr_response = self._ocr_document(path)
      if ocr_response is None:
          return None
  
      # Cache the document using model_dump_json() for direct JSON serialization
      try:
          with open(cached_document_path, "w") as f:
              f.write(ocr_response.model_dump_json(indent=2))
          logging.info(f"Successfully cached document {path.name}")
      except Exception as e:
          logging.error(f"Failed to cache document {path.name}: {e}")
  
      return ocr_response

• main.py:66-100 (helper)

  Private helper method that performs the actual OCR using MistralAI API, including upload, processing, and cleanup, called by read_document.

  def _ocr_document(self, path: Path) -> OCRResponse | None:
      """OCR a document and return the OCRResponse."""
      try:
          # Upload the file to MistralAI
          uploaded_file = self.mistral.files.upload(
              file={
                  "file_name": path.stem,
                  "content": path.read_bytes(),
              },
              purpose="ocr",
          )
  
          # Process the uploaded file with OCR
          ocr_response = self.mistral.ocr.process(
              document={
                  "type": "file",
                  "file_id": uploaded_file.id,
              },
              model="mistral-ocr-latest",
              include_image_base64=True,
          )
  
          # Clean up the uploaded file
          try:
              self.mistral.files.delete(uploaded_file.id)
          except Exception as e:
              logging.warning(
                  f"Failed to delete uploaded file {uploaded_file.id}: {e}"
              )
  
          return ocr_response
  
      except Exception as e:
          logging.error(f"OCR processing failed for {path}: {e}")
          return None