MCP-PDF2MD

Instructions

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, []