inspect_pdf_form

Instructions

Implementation Reference

• mcp/src/docgen_mcp/server.py:354-367 (handler)

  The MCP tool handler for 'inspect_pdf_form'. Decodes the base64 PDF, delegates to dg.pdf_forms.inspect_fields(), and returns a JSON array of form field definitions.

  @mcp.tool()
  def inspect_pdf_form(pdf_base64: str) -> str:
      """Inspect form fields in a PDF and return their names, types, and current values.
  
      Args:
          pdf_base64: Base64-encoded PDF file with form fields.
  
      Returns:
          JSON array of form field definitions.
      """
      dg = _get_client()
      fields = dg.pdf_forms.inspect_fields(base64.b64decode(pdf_base64))
      from docgen._serialization import to_dict
      return json.dumps([to_dict(f) for f in fields])

• python/src/docgen/clients/pdf_forms.py:19-35 (helper)

  The PdfFormsClient.inspect_fields() method called by the handler. Sends a POST request to /api/pdf-forms/fields/base64 and deserializes the response into PdfFormField instances.

  def inspect_fields(self, pdf: FileInput) -> list[PdfFormField]:
      """Inspect form fields in a PDF.
  
      Args:
          pdf: PDF file (path, bytes, or base64).
  
      Returns:
          List of form fields found in the PDF.
      """
      data = self._transport.request_json(
          "POST", "/api/pdf-forms/fields/base64",
          json={"pdfBase64": to_base64(pdf)},
      )
      # API returns a list directly
      if isinstance(data, list):
          return [from_dict(PdfFormField, item) for item in data]
      return [from_dict(PdfFormField, item) for item in data.get("fields", [])]

• python/src/docgen/models/forms.py:8-28 (schema)

  The PdfFormField dataclass schema defining the structure of a form field returned by inspect_fields.

  @dataclass
  class PdfFormField:
      """A field found in a PDF AcroForm.
  
      Args:
          name: Field name.
          type: Field type (TEXT, CHECKBOX, RADIO, DROPDOWN, LISTBOX, SIGNATURE, BUTTON).
          value: Current field value.
          required: Whether the field is required.
          read_only: Whether the field is read-only.
          max_length: Maximum character length (for text fields).
          options: Available options (for dropdown/listbox/radio).
      """
  
      name: str
      type: str
      value: str | None = None
      required: bool = False
      read_only: bool = False
      max_length: int | None = None
      options: list[str] | None = None

• typescript/src/models/forms.ts:1-9 (schema)

  The TypeScript interface definition for PdfFormField, mirroring the Python schema.

  /** A form field detected in a PDF. */
  export interface PdfFormField {
    name: string;
    type: string;
    value?: string;
    options?: string[];
    required?: boolean;
    readOnly?: boolean;
  }

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

  The @mcp.tool() decorator on the inspect_pdf_form function registers it as an MCP tool with the FastMCP server.

  @mcp.tool()
  def inspect_pdf_form(pdf_base64: str) -> str:
      """Inspect form fields in a PDF and return their names, types, and current values.
  
      Args:
          pdf_base64: Base64-encoded PDF file with form fields.
  
      Returns:
          JSON array of form field definitions.
      """
      dg = _get_client()
      fields = dg.pdf_forms.inspect_fields(base64.b64decode(pdf_base64))
      from docgen._serialization import to_dict
      return json.dumps([to_dict(f) for f in fields])