read_pdf_forms_info

Instructions

Extracts information about fillable PDF fields from an input PDF file.
Ref: https://developer.pdf.co/api-reference/forms/info-reader.md

Implementation Reference

• pdfco/mcp/tools/apis/form.py:1-38 (handler)

  The 'read_pdf_forms_info' tool handler function. Decorated with @mcp.tool() on line 8, this async function takes a URL and optional params (httpusername, httppassword, password, api_key), constructs a ConversionParams, and delegates to get_pdf_form_fields_info service function.

  from pdfco.mcp.server import mcp
  from pdfco.mcp.services.pdf import get_pdf_form_fields_info, fill_pdf_form_fields
  from pdfco.mcp.models import BaseResponse, ConversionParams
  
  from pydantic import Field
  
  
  @mcp.tool()
  async def read_pdf_forms_info(
      url: str = Field(
          description="URL to the source PDF file. Supports publicly accessible links including Google Drive, Dropbox, PDF.co Built-In Files Storage. Use 'upload_file' tool to upload local files."
      ),
      httpusername: str = Field(
          description="HTTP auth user name if required to access source url. (Optional)",
          default="",
      ),
      httppassword: str = Field(
          description="HTTP auth password if required to access source url. (Optional)",
          default="",
      ),
      password: str = Field(description="Password of PDF file. (Optional)", default=""),
      api_key: str = Field(
          description="PDF.co API key. If not provided, will use X_API_KEY environment variable. (Optional)",
          default="",
      ),
  ) -> BaseResponse:
      """
      Extracts information about fillable PDF fields from an input PDF file.
      Ref: https://developer.pdf.co/api-reference/forms/info-reader.md
      """
      params = ConversionParams(
          url=url,
          httpusername=httpusername,
          httppassword=httppassword,
          password=password,
      )
  
      return await get_pdf_form_fields_info(params, api_key=api_key)

• pdfco/mcp/services/pdf.py:26-29 (helper)

  The service/helper function 'get_pdf_form_fields_info' that makes the actual API call to 'pdf/info/fields' endpoint. Called by the read_pdf_forms_info handler.

  async def get_pdf_form_fields_info(
      params: ConversionParams, api_key: str | None = None
  ) -> BaseResponse:
      return await request("pdf/info/fields", params, api_key=api_key)

• pdfco/mcp/models.py:13-159 (schema)

  The ConversionParams model (lines 13-159) used by read_pdf_forms_info and BaseResponse model (lines 5-10) used as the return type. ConversionParams includes url, httpusername, httppassword, password and other fields.

  class ConversionParams(BaseModel):
      url: str = Field(
          description="URL to the source file. Supports publicly accessible links including Google Drive, Dropbox, PDF.co Built-In Files Storage. Use 'upload_file' tool to upload local files.",
          default="",
      )
      httpusername: str = Field(
          description="HTTP auth user name if required to access source url. (Optional)",
          default="",
      )
      httppassword: str = Field(
          description="HTTP auth password if required to access source url. (Optional)",
          default="",
      )
      pages: str = Field(
          description="Comma-separated page indices (e.g., '0, 1, 2-' or '1, 3-7'). Use '!' for inverted page numbers (e.g., '!0' for last page). Processes all pages if None. (Optional)",
          default="",
      )
      unwrap: bool = Field(
          description="Unwrap lines into a single line within table cells when lineGrouping is enabled. Must be true or false. (Optional)",
          default=False,
      )
      rect: str = Field(
          description="Defines coordinates for extraction (e.g., '51.8,114.8,235.5,204.0'). (Optional)",
          default="",
      )
      lang: str = Field(
          description="Language for OCR for scanned documents. Default is 'eng'. See PDF.co docs for supported languages. (Optional, Default: 'eng')",
          default="eng",
      )
      line_grouping: str = Field(
          description="Enables line grouping within table cells when set to '1'. (Optional)",
          default="0",
      )
      password: str = Field(
          description="Password of the PDF file. (Optional)", default=""
      )
      name: str = Field(
          description="File name for the generated output. (Optional)", default=""
      )
      autosize: bool = Field(
          description="Controls automatic page sizing. If true, page dimensions adjust to content. If false, uses worksheet’s page setup. (Optional)",
          default=False,
      )
  
      html: str = Field(
          description="Input HTML code to be converted. To convert the link to a PDF use the /pdf/convert/from/url endpoint instead.",
          default="",
      )
      templateId: str = Field(
          description="Set to the ID of your HTML template. You can find and copy the ID from HTML to PDF Templates.",
          default="",
      )
      templateData: str = Field(
          description="Set it to a string with input JSON data (recommended) or CSV data.",
          default="",
      )
      margins: str = Field(
          description="Set to CSS style margins like 10px, 5mm, 5in for all sides or 5px 5px 5px 5px (the order of margins is top, right, bottom, left). (Optional)",
          default="",
      )
      paperSize: str = Field(
          description="A4 is set by default. Can be Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, A6 or a custom size. Custom size can be set in px (pixels), mm or in (inches) with width and height separated by space like this: 200 300, 200px 300px, 200mm 300mm, 20cm 30cm or 6in 8in. (Optional)",
          default="",
      )
      orientation: str = Field(
          description="Set to Portrait or Landscape. Portrait is set by default. (Optional)",
          default="",
      )
      printBackground: bool = Field(
          description="true by default. Set to false to disable printing of background. (Optional)",
          default=True,
      )
      mediaType: str = Field(
          description="Uses print by default. Set to screen to convert HTML as it appears in a browser or print to convert as it appears for printing or none to set none as mediaType for CSS styles. (Optional)",
          default="",
      )
      DoNotWaitFullLoad: bool = Field(
          description="false by default. Set to true to skip waiting for full load (like full video load etc. that may affect the total conversion time). (Optional)",
          default=False,
      )
      header: str = Field(
          description="User definable HTML for the header to be applied on every page header. (Optional)",
          default="",
      )
      footer: str = Field(
          description="User definable HTML for the footer to be applied on every page footer. (Optional)",
          default="",
      )
  
      worksheetIndex: str = Field(
          description="Index of the worksheet to convert. (Optional)", default=""
      )
  
      def parse_payload(self, async_mode: bool = True):
          payload = {
              "async": async_mode,
          }
          if self.url:
              payload["url"] = self.url
          if self.httpusername:
              payload["httpusername"] = self.httpusername
          if self.httppassword:
              payload["httppassword"] = self.httppassword
          if self.pages:
              payload["pages"] = self.pages
          if self.unwrap:
              payload["unwrap"] = self.unwrap
          if self.rect:
              payload["rect"] = self.rect
          if self.lang:
              payload["lang"] = self.lang
          if self.line_grouping:
              payload["lineGrouping"] = self.line_grouping
          if self.password:
              payload["password"] = self.password
          if self.name:
              payload["name"] = self.name
          if self.autosize:
              payload["autosize"] = self.autosize
  
          if self.html:
              payload["html"] = self.html
          if self.templateId:
              payload["templateId"] = self.templateId
          if self.templateData:
              payload["templateData"] = self.templateData
          if self.margins:
              payload["margins"] = self.margins
          if self.paperSize:
              payload["paperSize"] = self.paperSize
          if self.orientation:
              payload["orientation"] = self.orientation
          if self.printBackground:
              payload["printBackground"] = self.printBackground
          if self.mediaType:
              payload["mediaType"] = self.mediaType
          if self.DoNotWaitFullLoad:
              payload["DoNotWaitFullLoad"] = self.DoNotWaitFullLoad
          if self.header:
              payload["header"] = self.header
          if self.footer:
              payload["footer"] = self.footer
  
          if self.worksheetIndex:
              payload["worksheetIndex"] = self.worksheetIndex
  
          return payload

• pdfco/mcp/server.py:1-3 (registration)

  The MCP server instance 'mcp' created via FastMCP('pdfco'). The @mcp.tool() decorator on the read_pdf_forms_info function registers it as an MCP tool.

  from fastmcp import FastMCP
  
  mcp = FastMCP("pdfco")

• pdfco/mcp/services/client.py:1-58 (helper)

  The HTTP client (PDFCoClient) used to make the API request to PDF.co. Handles API key resolution from parameter or environment variable, and manages the async HTTP session.

  from contextlib import asynccontextmanager
  from httpx import AsyncClient
  import os
  import sys
  from typing import AsyncGenerator
  import importlib.metadata
  
  __BASE_URL = "https://api.pdf.co"
  X_API_KEY = os.getenv("X_API_KEY")
  
  __version__ = importlib.metadata.version("pdfco-mcp")
  print(f"pdfco-mcp version: {__version__}", file=sys.stderr)
  
  
  @asynccontextmanager
  async def PDFCoClient(api_key: str | None = None) -> AsyncGenerator[AsyncClient, None]:
      # Use provided API key, fall back to environment variable
      x_api_key = api_key or X_API_KEY
  
      if not x_api_key:
          raise ValueError("""API key is required. Please provide an API key as a parameter or set X_API_KEY in the environment variables.
          
          To get the API key:
          1. Sign up at https://pdf.co
          2. Get the API key from the dashboard
          3. Either set it as an environment variable or provide it as a parameter
          
          Environment variable setup example (.cursor/mcp.json):
          ```json
          {
              "mcpServers": {
                  "pdfco": {
                      "command": "uvx",
                      "args": [
                          "pdfco-mcp"
                      ],
                      "env": {
                          "X_API_KEY": "YOUR_API_KEY"
                      }
                  }
              }
          }
          ```
          
          Or provide the API key as a parameter when calling the tool.
          """)
  
      client = AsyncClient(
          base_url=__BASE_URL,
          headers={
              "x-api-key": x_api_key,
              "User-Agent": f"pdfco-mcp/{__version__}",
          },
      )
      try:
          yield client
      finally:
          await client.aclose()