upload_file

Instructions

Implementation Reference

• pdfco/mcp/tools/apis/file.py:8-37 (handler)

  The upload_file MCP tool handler. It uploads a file to PDF.co API by posting to /v1/file/upload with the file content, and returns a BaseResponse with the uploaded file URL.

  @mcp.tool()
  async def upload_file(
      file_path: str = Field(description="The absolute path to the file to upload"),
      api_key: str = Field(
          description="PDF.co API key. If not provided, will use X_API_KEY environment variable. (Optional)",
          default="",
      ),
  ) -> BaseResponse:
      """
      Upload a file to the PDF.co API
      """
      try:
          async with PDFCoClient(api_key=api_key) as client:
              response = await client.post(
                  "/v1/file/upload",
                  files={
                      "file": open(file_path, "rb"),
                  },
              )
              res = response.json()
              return BaseResponse(
                  status="success" if res["status"] == 200 else "error",
                  content=res,
                  tips=f"You can use the url {res['url']} to access the file",
              )
      except Exception as e:
          return BaseResponse(
              status="error",
              content=str(e),
          )

• pdfco/mcp/models.py:5-10 (schema)

  The BaseResponse model used as the return type for the upload_file tool.

  class BaseResponse(BaseModel):
      status: str
      content: Any
      credits_used: int | None = None
      credits_remaining: int | None = None
      tips: str | None = None

• pdfco/mcp/__init__.py:3-15 (registration)

  Registration of the file module (containing upload_file) in the MCP server via import in __init__.py.

  from pdfco.mcp.tools.apis import (
      conversion,
      job,
      file,
      modification,
      form,
      search,
      searchable,
      security,
      document,
      extraction,
      editing,
  )

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

  The FastMCP server instance ('mcp') used as the decorator to register the upload_file tool.

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

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

  The PDFCoClient async context manager used by upload_file to authenticate and make HTTP requests to PDF.co API.

  @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()