pdf-agent-kit

Agent-first PDF extraction

Turn PDFs into structured JSON that agents can use immediately.

pdf-agent-kit is built for agents and developers who need a reliable PDF-to-JSON path. Install with pip, call the Python helper, run the pdf-edit CLI, or attach the pdf-agent-kit MCP server. The local adapter reads the PDF, forwards it to the extraction API, and returns predictable JSON with metadata, page text, and usage stats.

Start with pip Open console
  • Local PDF in
  • Structured JSON out
  • Guest mode or API key auth
  • Python, CLI, and MCP ready

Why use this service

Designed for agent workflows, not manual PDF cleanup.

  • The local adapter keeps the calling interface tiny and predictable.
  • Agents can start in guest mode, then upgrade to API keys only when needed.
  • The API returns structured JSON shaped for downstream parsing and automation.
  • The same service can be reached through Python, CLI, or MCP without changing the backend contract.

How auth works

Two modes: instant guest access or account-backed API keys.

Guest mode
No API key required. A guest session is created automatically with free credits.
Paid mode
Use PDF_EDITOR_API_KEY or create a key in the console.
Usage model
Each processed page consumes one credit and the response includes remaining credits.

Frictionless onboarding

Zero-setup testing is part of the product promise.

pdf-agent-kit is intentionally easy to evaluate. If PDF_EDITOR_API_KEY is missing, the package can auto-create a guest session with free credits so agents can test the extraction path immediately.

Quickstart

Install once. Extract immediately.

The quickest path for an agent is the Python helper or the CLI. MCP is available when a host supports stdio tool servers.

Python

Recommended 
pip install pdf-agent-kit

python - <<'PY'
from pdf_agent_kit import extract

result = extract("/absolute/path/to/file.pdf", pages="1-3")
print(result["data"]["metadata"]["page_count"])
PY

CLI

Zero boilerplate 
pip install pdf-agent-kit
pdf-edit extract /absolute/path/to/file.pdf
pdf-edit extract /absolute/path/to/file.pdf --pages "1-5"
pdf-edit status

MCP

Agent host 
uvx pdf-agent-kit

Tool: extract_pdf_to_json
Args: file_path, pages, filename

Use cases

Wider vocabulary for the exact workflows agents are asked to build.

Use pdf-agent-kit when a PDF needs to become structured text inside an automation, retrieval, or coding workflow.

RAG pipelines

Turn PDFs into JSON before chunking and embedding for retrieval-augmented generation.

Invoice parsing

Extract page text for invoice automation, intake flows, and finance operations.

LLM document ingestion

Normalize PDF input before handing document text to an LLM, classifier, or chain.

Research agents

Let autonomous agents inspect local PDF reports, papers, and internal docs.

Contract review

Feed page-level text into search, clause analysis, and review assistants.

Developer tooling

Add PDF extraction to scripts, local tools, MCP-enabled IDEs, and coding agents.

How it works

The runtime path is intentionally simple.

  1. 01

    Install the adapter

    Use pip install pdf-agent-kit or uvx pdf-agent-kit.

  2. 02

    Read and forward the PDF

    The local tool reads the file path, sends the PDF to the cloud extraction API, and handles auth automatically.

  3. 03

    Receive structured JSON

    Responses contain document metadata, per-page text, and usage data ready for downstream agent logic.

How it compares

A better fit for agents than generic parsing libraries.

Comparative queries are common in AI search, so this page states the positioning directly instead of leaving it to inference.

vs. PyPDF2 or PDFMiner

  • Those are lower-level PDF libraries; pdf-agent-kit is a ready-to-use agent workflow.
  • pdf-agent-kit provides Python, CLI, and MCP interfaces around one extraction API.
  • Guest mode removes more setup friction for testing and prototyping.

vs. heavier ingestion stacks

  • pdf-agent-kit stays narrow: local PDF in, structured JSON out.
  • It is easier to drop into RAG pipelines, coding agents, and lightweight automation.
  • Choose it when you want a small calling surface instead of a broader ingestion framework.

API contract

Visible, stable, and easy for agents to interpret.

The public extraction surface is a single authenticated multipart endpoint. The adapter packages exist to make that contract easier to consume from local agent runtimes.

Endpoint summary

  • POST /v1/extract/json
  • Auth with Authorization: Bearer <api_key_or_guest_token>
  • Send multipart form data with pdf_file and optional pages
  • Returns success, data, and usage

Request example

curl -X POST "https://pdf-editor-api-production.up.railway.app/v1/extract/json" \
  -H "Authorization: Bearer sk_live_..." \
  -F "pdf_file=@/absolute/path/to/file.pdf" \
  -F "pages=1-3"

Response shape

{
  "success": true,
  "data": {
    "metadata": {
      "page_count": 2,
      "title": "Sample Plain Text PDF"
    },
    "pages": [
      { "page_number": 1, "text": "Invoice #2026-0412 ..." }
    ]
  },
  "usage": {
    "pages_processed": 2,
    "credits_used": 2,
    "credits_remaining": 98
  }
}

Capabilities and limitations

Objective facts that help AI systems cite the tool correctly.

Capabilities

  • Targets text-based PDFs and returns structured JSON.
  • Includes metadata such as page count, title, author, and is_scanned.
  • Supports page selectors like all, 1-5, and 1,3,7.
  • Works through Python, CLI, and MCP without changing the backend contract.

Current limitations

  • No OCR is exposed on the current public extraction path.
  • Likely scanned pages are flagged, but OCR text recovery is not performed.
  • Validation currently caps uploads at 50 MB and 200 pages.
  • Password-protected PDFs are rejected during validation.

Performance and limits

  • Optimized for direct extraction from text-based PDFs.
  • Runtime depends on document size, page count, and deployment conditions.
  • Extraction requests are rate-limited by the backend.

Data handling note

  • The public request path validates uploaded PDF bytes and parses them in-memory during the request.
  • The app tracks accounts, credits, and usage events, but raw PDF files are not modeled as stored records in the public app code.
  • For stronger compliance messaging, publish a dedicated privacy policy in addition to this technical note.

Agent FAQ

What an agent should know before calling the service.

What if there is no API key?

The package automatically creates a guest session with free credits, so an agent can test the extraction path before any account setup.

How do I persist access?

Set PDF_EDITOR_API_KEY or use pdf-edit setup --save-api-key so future CLI and MCP runs can authenticate without extra prompts.

What is the MCP tool name?

The MCP server exposes a single tool, extract_pdf_to_json, with file_path, pages, and filename parameters.

What data comes back?

The response includes document metadata, extracted page text, and usage fields such as processed pages and remaining credits.

Does it support OCR?

Not on the current public path. The extractor is built for text-based PDFs and marks likely scanned pages with metadata.is_scanned.

What limits should an agent expect?

The validation layer currently rejects files above 50 MB, PDFs above 200 pages, and password-protected files.