PDF Manipulation MCP Server

Instructions

Implementation Reference

• pdf_manipulation_mcp_server/pdf_server.py:333-395 (handler)

  The core handler function for the 'pdf_add_form_field' tool. Decorated with @mcp.tool() for automatic registration in FastMCP. Adds interactive form fields (text, checkbox, radio button, or combobox) to a specified position on a PDF page using PyMuPDF. Validates input, creates the widget, updates it, saves to a new timestamped file, and returns the output path.

  async def pdf_add_form_field(
      pdf_path: str,
      page_number: int,
      field_type: str,
      field_name: str,
      x: float,
      y: float,
      width: float,
      height: float,
      options: List[str] = None
  ) -> str:
      """Add a form field to a PDF."""
      if options is None:
          options = []
      
      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)
          
          # 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
          page = doc[page_number]
          
          # Create rectangle for form field
          rect = fitz.Rect(x, y, x + width, y + height)
          
          # Add form field based on type
          if field_type == "text":
              widget = page.add_textfield(rect, field_name)
          elif field_type == "checkbox":
              widget = page.add_checkbox(rect, field_name)
          elif field_type == "radio":
              widget = page.add_radio_button(rect, field_name)
          elif field_type == "combobox":
              widget = page.add_combobox(rect, field_name, options)
          else:
              doc.close()
              return f"Error: Invalid field type: {field_type}"
          
          # Update widget appearance
          widget.update()
          
          # Generate output filename
          output_path = generate_output_filename(pdf_path)
          
          # Save the modified PDF
          doc.save(output_path)
          doc.close()
          
          return f"Successfully added {field_type} form field '{field_name}' to PDF. Output saved to: {output_path}"
          
      except Exception as e:
          return f"Error adding form field to PDF: {str(e)}"