PDF.co MCP Server

Instructions

AI Invoice Parser: Extracts data from invoices using AI.
Ref: https://developer.pdf.co/api-reference/ai-invoice-parser.md

Implementation Reference

• pdfco/mcp/tools/apis/extraction.py:8-29 (handler)

  The core handler function for the 'ai_invoice_parser' tool, registered via @mcp.tool() decorator. Defines input schema (url and optional api_key) using Pydantic Field for descriptions and validation. Prepares ConversionParams and delegates to parse_invoice helper for API execution.

  @mcp.tool()
  async def ai_invoice_parser(
      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."
      ),
      api_key: str = Field(
          description="PDF.co API key. If not provided, will use X_API_KEY environment variable. (Optional)",
          default="",
      ),
  ) -> BaseResponse:
      """
      AI Invoice Parser: Extracts data from invoices using AI.
      Ref: https://developer.pdf.co/api-reference/ai-invoice-parser.md
      """
  
      # Pass arguments directly; ConversionParams now handles str with default=None
      params = ConversionParams(
          url=url,
      )
  
      return await parse_invoice(params, api_key=api_key)

• pdfco/mcp/services/pdf.py:115-116 (helper)

  Helper function that performs the specific HTTP request to the PDF.co 'ai-invoice-parser' API endpoint using the general request function.

  async def parse_invoice(params: ConversionParams, api_key: str | None = None) -> BaseResponse:
      return await request("ai-invoice-parser", params, api_key=api_key)

• pdfco/mcp/services/pdf.py:125-154 (helper)

  General-purpose HTTP request helper used by parse_invoice (and other tools) to call PDF.co API endpoints asynchronously, handling payload preparation, client usage, response parsing, and error handling.

  async def request(
      endpoint: str,
      params: ConversionParams,
      custom_payload: dict | None = None,
      api_key: str | None = None,
  ) -> BaseResponse:
      payload = params.parse_payload(async_mode=True)
      if custom_payload:
          payload.update(custom_payload)
  
      try:
          async with PDFCoClient(api_key=api_key) as client:
              url = f"/v1/{endpoint}"
              print(f"Requesting {url} with payload {payload}", file=sys.stderr)
              response = await client.post(url, json=payload)
              print(f"response: {response}", file=sys.stderr)
              json_data = response.json()
              return BaseResponse(
                  status="working",
                  content=json_data,
                  credits_used=json_data.get("credits"),
                  credits_remaining=json_data.get("remainingCredits"),
                  tips=f"You **should** use the 'wait_job_completion' tool to wait for the job [{json_data.get('jobId')}] to complete if a jobId is present.",
              )
      except Exception as e:
          return BaseResponse(
              status="error",
              content=f"{type(e)}: {[arg for arg in e.args if arg]}",
          )