PDF Manipulation MCP Server

Instructions

Implementation Reference

• pdf_manipulation_mcp_server/pdf_server.py:491-589 (handler)

  The complete handler function for 'pdf_combine_pages_to_single' tool, including @mcp.tool() decorator for registration, type-annotated parameters serving as input schema, docstring description, and full implementation using PyMuPDF (fitz) to combine PDF pages into a single page with vertical, horizontal, or grid layouts.

  @mcp.tool()
  async def pdf_combine_pages_to_single(
      pdf_path: str,
      page_numbers: Optional[List[int]] = None,
      layout: str = "vertical",
      output_path: Optional[str] = None
  ) -> str:
      """Combine multiple pages from a PDF into a single page with specified layout."""
      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 layout not in ["vertical", "horizontal", "grid"]:
          return f"Error: Invalid layout. Must be 'vertical', 'horizontal', or 'grid'."
      
      try:
          # Open PDF document
          doc = fitz.open(pdf_path)
          
          # Determine pages to combine
          if page_numbers is None:
              pages_to_combine = list(range(len(doc)))
          else:
              # Validate page numbers
              for page_num in page_numbers:
                  if not validate_page_number(doc, page_num):
                      doc.close()
                      return f"Error: Invalid page number {page_num}. Document has {len(doc)} pages."
              pages_to_combine = page_numbers
          
          if len(pages_to_combine) < 2:
              doc.close()
              return "Error: Need at least 2 pages to combine."
          
          # Get dimensions of all pages
          page_rects = [doc[page_num].rect for page_num in pages_to_combine]
          page_widths = [rect.width for rect in page_rects]
          page_heights = [rect.height for rect in page_rects]
          
          # Calculate new page dimensions based on layout
          if layout == "vertical":
              new_width = max(page_widths)
              new_height = sum(page_heights)
          elif layout == "horizontal":
              new_width = sum(page_widths)
              new_height = max(page_heights)
          else:  # grid layout
              import math
              num_pages = len(pages_to_combine)
              cols = math.ceil(math.sqrt(num_pages))
              rows = math.ceil(num_pages / cols)
              new_width = max(page_widths) * cols
              new_height = max(page_heights) * rows
          
          # Create new document with single page
          new_doc = fitz.open()
          new_page = new_doc.new_page(width=new_width, height=new_height)
          
          # Place pages according to layout
          if layout == "vertical":
              y_offset = 0
              for page_num in pages_to_combine:
                  page_rect = fitz.Rect(0, y_offset, page_rects[pages_to_combine.index(page_num)].width, 
                                      y_offset + page_rects[pages_to_combine.index(page_num)].height)
                  new_page.show_pdf_page(page_rect, doc, page_num)
                  y_offset += page_rects[pages_to_combine.index(page_num)].height
                  
          elif layout == "horizontal":
              x_offset = 0
              for page_num in pages_to_combine:
                  page_rect = fitz.Rect(x_offset, 0, x_offset + page_rects[pages_to_combine.index(page_num)].width,
                                      page_rects[pages_to_combine.index(page_num)].height)
                  new_page.show_pdf_page(page_rect, doc, page_num)
                  x_offset += page_rects[pages_to_combine.index(page_num)].width
                  
          else:  # grid layout
              for i, page_num in enumerate(pages_to_combine):
                  row = i // cols
                  col = i % cols
                  x = col * max(page_widths)
                  y = row * max(page_heights)
                  page_rect = fitz.Rect(x, y, x + page_rects[i].width, y + page_rects[i].height)
                  new_page.show_pdf_page(page_rect, doc, page_num)
          
          # Generate output filename
          if not output_path:
              output_path = generate_output_filename(pdf_path, "combined")
          
          # Save the combined PDF
          new_doc.save(output_path)
          new_doc.close()
          doc.close()
          
          return f"Successfully combined {len(pages_to_combine)} pages using {layout} layout. Output saved to: {output_path}"
          
      except Exception as e:
          return f"Error combining pages: {str(e)}"

• pdf_manipulation_mcp_server/pdf_server.py:492-497 (schema)

  Input schema defined by function parameters with type hints: pdf_path (str), page_numbers (Optional[List[int]]), layout (str, default 'vertical'), output_path (Optional[str]); returns str (status message with output path).

  async def pdf_combine_pages_to_single(
      pdf_path: str,
      page_numbers: Optional[List[int]] = None,
      layout: str = "vertical",
      output_path: Optional[str] = None
  ) -> str: