PDF Manipulation MCP Server

Instructions

Implementation Reference

• pdf_manipulation_mcp_server/pdf_server.py:591-655 (handler)

  The primary handler implementation for the 'pdf_split' MCP tool. This async function handles splitting a PDF file into individual pages or custom page ranges using PyMuPDF (fitz). The @mcp.tool() decorator registers it automatically in the FastMCP server. Input parameters define the schema via type hints.

  @mcp.tool()
  async def pdf_split(
      pdf_path: str,
      output_dir: Optional[str] = None,
      page_ranges: Optional[List[Dict[str, int]]] = None
  ) -> str:
      """Split a PDF into individual pages or page ranges."""
      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}"
      
      try:
          # Open PDF document
          doc = fitz.open(pdf_path)
          
          # Determine output directory
          if not output_dir:
              pdf_file = Path(pdf_path)
              output_dir = str(pdf_file.parent / f"{pdf_file.stem}_split")
          
          # Create output directory
          os.makedirs(output_dir, exist_ok=True)
          
          split_files = []
          
          if page_ranges:
              # Split by page ranges
              for i, page_range in enumerate(page_ranges):
                  start_page = page_range["start"]
                  end_page = page_range["end"]
                  
                  # Validate page range
                  if start_page < 0 or end_page >= len(doc) or start_page > end_page:
                      doc.close()
                      return f"Error: Invalid page range {start_page}-{end_page}"
                  
                  # Create new document for this range
                  new_doc = fitz.open()
                  new_doc.insert_pdf(doc, from_page=start_page, to_page=end_page)
                  
                  # Save split PDF
                  output_file = os.path.join(output_dir, f"pages_{start_page + 1}_to_{end_page + 1}.pdf")
                  new_doc.save(output_file)
                  new_doc.close()
                  split_files.append(output_file)
          else:
              # Split into individual pages
              for page_num in range(len(doc)):
                  new_doc = fitz.open()
                  new_doc.insert_pdf(doc, from_page=page_num, to_page=page_num)
                  
                  output_file = os.path.join(output_dir, f"page_{page_num + 1}.pdf")
                  new_doc.save(output_file)
                  new_doc.close()
                  split_files.append(output_file)
          
          doc.close()
          
          return f"Successfully split PDF into {len(split_files)} files. Output directory: {output_dir}"
          
      except Exception as e:
          return f"Error splitting PDF: {str(e)}"