fill_pdf_form

Instructions

Implementation Reference

• mcp/src/docgen_mcp/server.py:370-388 (handler)

  MCP tool handler for 'fill_pdf_form'. Accepts pdf_base64 (str), fields (dict[str,str]), and flatten (bool). Decodes the PDF, calls dg.fill_form(), and returns a base64-encoded filled PDF.

  @mcp.tool()
  def fill_pdf_form(
      pdf_base64: str,
      fields: dict[str, str],
      flatten: bool = False,
  ) -> str:
      """Fill form fields in a PDF.
  
      Args:
          pdf_base64: Base64-encoded PDF file with form fields.
          fields: Field name-value pairs to fill.
          flatten: Whether to flatten the form (make fields non-editable).
  
      Returns:
          Base64-encoded filled PDF.
      """
      dg = _get_client()
      result = dg.fill_form(base64.b64decode(pdf_base64), fields, flatten)
      return base64.b64encode(result).decode()

• mcp/src/docgen_mcp/server.py:370-370 (registration)

  The tool is registered as an MCP tool via the @mcp.tool() decorator on the fill_pdf_form function.

  @mcp.tool()

• python/src/docgen/clients/pdf_forms.py:37-64 (helper)

  Low-level fill method on PdfFormsClient that sends a POST request to /api/pdf-forms/fill. It builds a PdfFormFillRequest and returns the filled PDF bytes.

  def fill(
      self,
      pdf: FileInput,
      fields: dict[str, str],
      *,
      flatten: bool = False,
      password: str | None = None,
  ) -> bytes:
      """Fill form fields in a PDF.
  
      Args:
          pdf: PDF file with form fields.
          fields: Field values to fill (name → value).
          flatten: Make fields non-editable after filling.
          password: Optional password for the output PDF.
  
      Returns:
          Filled PDF bytes.
      """
      request = PdfFormFillRequest(
          pdf_base64=to_base64(pdf),
          fields=fields,
          flatten=flatten,
          password=password,
      )
      return self._transport.request_bytes(
          "POST", "/api/pdf-forms/fill", json=to_dict(request)
      )

• python/src/docgen/client.py:241-257 (helper)

  DocGen client's fill_form method that delegates to PdfFormsClient.fill(). This is the intermediate call made by the MCP handler.

  def fill_form(
      self,
      pdf: FileInput,
      fields: dict[str, str],
      **kwargs: Any,
  ) -> bytes:
      """Fill PDF form fields.
  
      Args:
          pdf: PDF with form fields.
          fields: Field values (name → value).
          **kwargs: Additional options (flatten, password).
  
      Returns:
          Filled PDF bytes.
      """
      return self._pdf_forms.fill(pdf, fields, **kwargs)

• python/src/docgen/models/forms.py:31-45 (schema)

  PdfFormFillRequest dataclass - the request schema used to fill PDF form fields. Contains pdf_base64, fields dict, flatten flag, and optional password.

  @dataclass
  class PdfFormFillRequest:
      """Request to fill PDF form fields.
  
      Args:
          pdf_base64: Base64-encoded PDF with form fields.
          fields: Field values to fill (name → value).
          flatten: Whether to flatten the form after filling (makes fields non-editable).
          password: Optional password for the filled PDF.
      """
  
      pdf_base64: str
      fields: dict[str, str] = field(default_factory=dict)
      flatten: bool = False
      password: str | None = None