PDF Manipulation MCP Server

Instructions

Implementation Reference

• pdf_manipulation_mcp_server/pdf_server.py:656-696 (handler)

  The core handler function for the 'pdf_rotate_page' tool. Decorated with @mcp.tool() for automatic registration in FastMCP. Validates input PDF and page, rotates the specified page using PyMuPDF's set_rotation(), generates output filename, and saves the modified PDF.

  @mcp.tool()
  async def pdf_rotate_page(
      pdf_path: str,
      page_number: int,
      rotation: int
  ) -> str:
      """Rotate a page in a PDF."""
      if not os.path.exists(pdf_path):
          return f"Error: PDF file not found: {pdf_path}"
      
      if not validate_pdf_file(pdf_path):
          return f"Error: Invalid PDF file: {pdf_path}"
      
      if rotation not in [90, 180, 270]:
          return f"Error: Invalid rotation angle. Must be 90, 180, or 270 degrees."
      
      try:
          # Open PDF document
          doc = fitz.open(pdf_path)
          
          # Validate page number
          if not validate_page_number(doc, page_number):
              doc.close()
              return f"Error: Invalid page number {page_number}. Document has {len(doc)} pages."
          
          # Get the page and rotate it
          page = doc[page_number]
          page.set_rotation(rotation)
          
          # Generate output filename
          output_path = generate_output_filename(pdf_path)
          
          # Save the modified PDF
          doc.save(output_path)
          doc.close()
          
          return f"Successfully rotated page {page_number + 1} by {rotation} degrees. Output saved to: {output_path}"
          
      except Exception as e:
          return f"Error rotating page: {str(e)}"

• pdf_manipulation_mcp_server/pdf_server.py:37-39 (helper)

  Helper function used by pdf_rotate_page to validate the page number exists in the document.

  def validate_page_number(doc: fitz.Document, page_num: int) -> bool:
      """Validate that the page number exists in the document."""
      return 0 <= page_num < len(doc)

• pdf_manipulation_mcp_server/pdf_server.py:28-35 (helper)

  Helper function used by pdf_rotate_page to validate the input is a valid PDF file.

  def validate_pdf_file(pdf_path: str) -> bool:
      """Validate that the file is a valid PDF."""
      try:
          doc = fitz.open(pdf_path)
          doc.close()
          return True
      except Exception:
          return False

• pdf_manipulation_mcp_server/pdf_server.py:22-26 (helper)

  Helper function used by pdf_rotate_page to generate a timestamped output filename.

  def generate_output_filename(input_path: str, suffix: str = "modified") -> str:
      """Generate a new filename with timestamp to avoid overwriting originals."""
      path = Path(input_path)
      timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
      return str(path.parent / f"{path.stem}_{suffix}_{timestamp}{path.suffix}")