convert_pdf_url

Instructions

Convert a PDF from a URL to Markdown. The output is saved in the directory specified by --output-dir.

Args:
    url: A single PDF URL or multiple URLs separated by spaces, commas, or newlines.

Returns:
    A dictionary with the conversion results.

Implementation Reference

• src/pdf2md/server.py:79-79 (registration)

  Registers the convert_pdf_url function as an MCP tool using the FastMCP decorator.

  @mcp.tool()

• src/pdf2md/server.py:80-142 (handler)

  The core implementation of the convert_pdf_url tool. Downloads the PDF from the URL, encodes it to base64, processes it with Mistral OCR API, saves the resulting markdown and any images to a subdirectory in OUTPUT_DIR.

  async def convert_pdf_url(url: str) -> Dict[str, Any]:
      """
      Convert a PDF from a URL to Markdown. The output is saved in the directory specified by --output-dir.
  
      Args:
          url: A single PDF URL or multiple URLs separated by spaces, commas, or newlines.
  
      Returns:
          A dictionary with the conversion results.
      """
      if not MISTRAL_API_KEY:
          return {"success": False, "error": "Missing API key, please set environment variable MISTRAL_API_KEY"}
  
      try:
          client = Mistral(api_key=MISTRAL_API_KEY)
      except Exception as e:
          return {"success": False, "error": f"Error initializing Mistral client: {e}"}
  
      urls = parse_input_string(url)
      results = []
  
      async with httpx.AsyncClient(timeout=120.0) as http_client:
          for u in urls:
              try:
                  response = await http_client.get(u, follow_redirects=True)
                  response.raise_for_status()
                  base64_pdf = base64.b64encode(response.content).decode('utf-8')
  
                  pdf_name = Path(u.split('?')[0]).stem
                  # Create a specific subdirectory for this URL's content
                  output_dir = Path(OUTPUT_DIR) / pdf_name
                  output_dir.mkdir(parents=True, exist_ok=True)
  
                  output_md_path = output_dir / f"{pdf_name}.md"
  
                  ocr_response = client.ocr.process(
                      model="mistral-ocr-latest",
                      document={"type": "document_url", "document_url": f"data:application/pdf;base64,{base64_pdf}"},
                      include_image_base64=True
                  )
  
                  markdown_content, saved_images = save_ocr_response_to_markdown_and_images(
                      ocr_response, output_md_path, output_dir
                  )
  
                  if markdown_content is not None:
                      results.append({
                          "url": u,
                          "success": True,
                          "markdown_file": str(output_md_path),
                          "images": saved_images,
                          "output_directory": str(output_dir),
                          "content_length": len(markdown_content)
                      })
                  else:
                      results.append({"url": u, "success": False, "error": "Could not save markdown or images."})
  
              except httpx.RequestError as e:
                  results.append({"url": u, "success": False, "error": f"Failed to download URL: {e}"})
              except Exception as e:
                  results.append({"url": u, "success": False, "error": f"Error processing URL '{u}': {e}"})
  
      return {"success": any(r.get("success", False) for r in results), "results": results}

• src/pdf2md/server.py:81-89 (schema)

  Docstring providing input/output schema: input is str url (supports multiple), output is dict with 'success' bool and 'results' list of per-URL dicts containing paths and status.

  """
  Convert a PDF from a URL to Markdown. The output is saved in the directory specified by --output-dir.
  
  Args:
      url: A single PDF URL or multiple URLs separated by spaces, commas, or newlines.
  
  Returns:
      A dictionary with the conversion results.
  """

• src/pdf2md/server.py:61-75 (helper)

  Helper utility to parse the input url string into a list of individual URLs, handling quotes and separators.

  def parse_input_string(input_string: str) -> List[str]:
      """Parses a string of paths or URLs separated by spaces, commas, or newlines."""
      if (input_string.startswith('"') and input_string.endswith('"')) or \
         (input_string.startswith("'") and input_string.endswith("'")):
          input_string = input_string[1:-1]
      items = " ".join(input_string.replace(",", " ").split()).split()
      cleaned_items = []
      for item in items:
          if (item.startswith('"') and item.endswith('"')) or \
             (item.startswith("'") and item.endswith("'")):
              cleaned_items.append(item[1:-1])
          else:
              cleaned_items.append(item)
      return [item for item in cleaned_items if item]

• src/pdf2md/server.py:40-60 (helper)

  Helper function to process OCR response: writes markdown from pages to file, saves base64 images using save_image, returns content and image paths.

  def save_ocr_response_to_markdown_and_images(ocr_response, output_md_path, output_dir_for_images):
      """
      Saves the markdown content from each page of the OCR response to a file
      and saves any associated images.
      """
      full_markdown_content = []
      saved_images = []
      try:
          with open(output_md_path, "wt", encoding='utf-8') as f:
              for page in ocr_response.pages:
                  f.write(page.markdown)
                  full_markdown_content.append(page.markdown)
                  for image in page.images:
                      saved_image_path = save_image(image, output_dir_for_images)
                      if saved_image_path:
                          saved_images.append(saved_image_path)
          return "".join(full_markdown_content), saved_images
      except Exception as e:
          print(f"Error saving markdown file '{output_md_path}' or processing images: {e}")
          return None, []