pdf_fill_form

Instructions

Implementation Reference

• pdf_manipulation_mcp_server/pdf_server.py:397-452 (handler)

  Primary handler implementation for the 'pdf_fill_form' tool. Uses PyMuPDF to iterate through PDF pages and widgets, filling form fields matching keys in field_values dictionary based on widget type. Includes input validation, error handling, and saves output to timestamped file. The @mcp.tool() decorator handles registration and schema inference from type hints and docstring.

  @mcp.tool()
  async def pdf_fill_form(
      pdf_path: str,
      field_values: Dict[str, Any]
  ) -> str:
      """Fill form fields in a PDF with values."""
      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)
          
          filled_fields = 0
          
          # Fill form fields
          for page_num in range(len(doc)):
              page = doc[page_num]
              widgets = page.widgets()
              
              for widget in widgets:
                  field_name = widget.field_name
                  if field_name in field_values:
                      value = field_values[field_name]
                      
                      # Set field value based on widget type
                      if widget.field_type == fitz.PDF_WIDGET_TYPE_TEXT:
                          widget.field_value = str(value)
                      elif widget.field_type == fitz.PDF_WIDGET_TYPE_CHECKBOX:
                          widget.field_value = bool(value)
                      elif widget.field_type == fitz.PDF_WIDGET_TYPE_RADIOBUTTON:
                          widget.field_value = str(value)
                      elif widget.field_type == fitz.PDF_WIDGET_TYPE_COMBOBOX:
                          widget.field_value = str(value)
                      
                      widget.update()
                      filled_fields += 1
          
          if filled_fields == 0:
              doc.close()
              return "No matching form fields found to fill."
          
          # Generate output filename
          output_path = generate_output_filename(pdf_path)
          
          # Save the modified PDF
          doc.save(output_path)
          doc.close()
          
          return f"Successfully filled {filled_fields} form fields. Output saved to: {output_path}"
          
      except Exception as e:
          return f"Error filling form fields: {str(e)}"

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

  Helper function used by pdf_fill_form to validate the input PDF file is valid by attempting to open it with PyMuPDF.

  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-27 (helper)

  Helper function used by pdf_fill_form to generate a timestamped output filename to prevent overwriting the original PDF.

  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}")

• pdf_manipulation_mcp_server/pdf_server.py:19-19 (registration)

  Initialization of the FastMCP server instance. All tools decorated with @mcp.tool() are automatically registered here.

  mcp = FastMCP("pdf-manipulation")