pymupdf4llm-mcp

Instructions

Implementation Reference

• pymupdf4llm_mcp/app.py:20-76 (handler)

  The handler function that executes the convert_pdf_to_markdown tool. It validates paths, converts PDF to markdown using pymupdf4llm.to_markdown, handles image saving, optional markdown file saving, truncation for long content, and error handling.
  def convert_pdf_to_markdown( file_path: Annotated[str, Field(description="Absolute path to the PDF file to convert")], image_path: Annotated[ str | None, Field( description="Optional. Absolute path to the directory to save the images. " "If not provided, the images will be saved in the same directory as the PDF file." ), ] = None, save_path: Annotated[ str | None, Field( description="Optional. Absolute path to the directory to save the markdown file. " "If provided, will return the path to the markdown file. " "If not provided, will return the markdown string." ), ] = None, ) -> dict[str, Any]: file_path: Path = Path(file_path).expanduser().resolve() if not file_path.exists(): return { "error": f"File not found: {file_path}", "success": False, } image_path = Path(image_path).expanduser().resolve() if image_path else file_path.parent try: content = pymupdf4llm.to_markdown(file_path, write_images=True, image_path=image_path.as_posix()) if save_path: save_path: Path = Path(save_path).expanduser().resolve() save_path.parent.mkdir(parents=True, exist_ok=True) content = pymupdf4llm.to_markdown(file_path, write_images=True, image_path=image_path.as_posix()) with open(save_path, "w", encoding="utf-8") as f: f.write(content) return { "success": True, "markdown_path": save_path.expanduser().resolve().absolute().as_posix(), } else: if len(content) > 10000: # Truncate the content to avoid too long response content = content[:10000] + "\n\n... (truncated)" tips = ( "The content is too long. Please use `save_path` to save the markdown file and read it partially." ) else: tips = "All content is returned. " return { "success": True, "markdown_content": content, "tips": tips, } except Exception as e: return { "error": f"Failed to convert PDF to markdown: {e!s}", "success": False, }
• pymupdf4llm_mcp/app.py:11-19 (registration)

  The @mcp.tool decorator registers the convert_pdf_to_markdown function as an MCP tool, providing a detailed description of its usage and parameters.
  @mcp.tool( description=( "Converts a PDF file to markdown format via pymupdf4llm. " "This is the best tool to use for reading PDF file. You should always use this tool first. " "The `file_path`, `image_path`, and `save_path` parameters should be the absolute path to the PDF file, not a relative path. " "This tool will also convert the PDF to images and save them in the `image_path` directory. " "For larger PDF files, use `save_path` to save the markdown file then read it partially. " ) )
• pymupdf4llm_mcp/app.py:21-36 (schema)

  Pydantic Field annotations define the input schema for the tool parameters: file_path (required str), image_path (optional str), save_path (optional str).
  file_path: Annotated[str, Field(description="Absolute path to the PDF file to convert")], image_path: Annotated[ str | None, Field( description="Optional. Absolute path to the directory to save the images. " "If not provided, the images will be saved in the same directory as the PDF file." ), ] = None, save_path: Annotated[ str | None, Field( description="Optional. Absolute path to the directory to save the markdown file. " "If provided, will return the path to the markdown file. " "If not provided, will return the markdown string." ), ] = None,
• pymupdf4llm_mcp/app.py:8-8 (registration)

  Initialization of the FastMCP server instance where tools are registered.
  mcp = FastMCP("pymupdf4llm-mcp")