pdf-reader-mcp

PDF Reader MCP is a local-first, public Model Context Protocol (MCP) package designed for PDF and document intelligence. It provides AI agents with typed tools for various document tasks including:

• Inspection & Search: PDF inspection, search, and document maps.
• Visual & Structural Analysis: Rendering, region crops, and accessibility reports.
• Data Extraction: OCR routing, extraction, and provenance tracking.
• Verification: Trust signals, benchmarks, and package release evidence.

The project is designed to be provider-neutral, offering optional OCR/vision interfaces while keeping document processing local-first by default. It emphasizes preserving source, page, and region provenance so that downstream agents can cite and verify evidence.

PDF Reader MCP (@sylphx/pdf-reader-mcp@4.1.1) is an evidence-first MCP server designed for AI agents to process PDFs. Instead of returning lossy text dumps, it provides an 'Agent Document Twin' containing markdown, tables, and source evidence.

The server exposes three primary V3 tools:

1. read_pdf: The smart default tool. When provided with sources, it profiles the PDF, selects an extraction route, and returns the Agent Document Twin.
2. search_pdf: Searches extracted text and returns snippets, offsets, bounding-box provenance, and optional OCR-layer matches.
3. pdf_evidence: Executes focused evidence operations, including inspect, render_page, extract_regions, ocr_pages, and analyze_regions.

The pdf-reader-mcp product provides a set of tools designed to give AI agents the ability to process and understand PDF documents. The tool surface is designed around a policy of providing a few, powerful, and obvious tools, prioritizing structured reading.

Available Tools

Interfaces

• CLI: Use the citra or pdf-reader-mcp commands for human or script-based interaction.
• SDK: Use the @sylphx/pdf-reader-mcp/sdk for programmatic integration into your own applications.

Citra can be consumed through three primary interfaces:

1. SDK: Programmatic access via import { Citra } from '@sylphx/pdf-reader-mcp/sdk'.
2. CLI: Command line access using citra or pdf-reader-mcp.
3. MCP: Model Context Protocol (MCP) via stdio tools, providing page-level evidence to AI agents.

The Agent Document Twin is the core data structure returned by the PDF Reader MCP. Instead of a plain-text dump, it provides a high-fidelity, linked map of the document that includes:

• Text & Structure: Text, tables, and layout diagnostics.
• Visual Evidence: Crops, OCR, and page rendering metadata.
• Citations & Provenance: Stable IDs and source references for retrieval workflows.
• Metadata & Geometry: Page counts, document properties, and page geometry.
• Signals: Trust reports (risk/redaction), accessibility reports (tag coverage/headings), and safety findings.

This structure allows AI agents to understand not just what the text says, but how it is visually and structurally organized.

The project exposes several surfaces depending on your integration needs:

• MCP Package and CLI: Delivered via npm (the main package and platform-optional native packages). The runtime entry is located at dist/runtime-entry.js (native only).
• Rust Core / Server: The authoritative production runtime is built using the crates/pdf-reader-core and crates/pdf-reader-mcp-server crates.
• Documentation: Comprehensive guides and tool specifications are available in README.md and the docs/ directory (including docs/specs/).
• Boundary Specifications: Architectural decisions regarding boundaries are documented in docs/adr/0001-2027-sota-document-intelligence-boundary.md.

If you are developing or using provider adapters for OCR, vision, or layout analysis within the @sylphx/pdf-reader-mcp ecosystem, they must adhere to the following constraints:

• Optionality: Must be an optional dependency or an optional runtime adapter.
• Credential Handling: Must accept credential handles from the caller environment; never hardcode keys.
• Transparency: Must explicitly declare whether documents leave the local machine.
• Data Integrity: Must return typed, provenance-preserving results (including page, bounding region, image, table, and source metadata).
• Metadata: Must expose cost, latency, and error metadata where available.
• Granular Failure: Must be capable of failing per page or per source.

The include_document_map option builds a rich, structured response that links pages, elements, metadata, chunks, and layout diagnostics without embedding heavy image bytes. It is the most efficient way for agents to navigate a document without rebuilding references manually.

If a visual-region provider is configured, you can also use include_visual_enrichments to get cropped and analyzed regions for tables, charts, and formulas. Keep max_visual_enrichments small for interactive workflows.

{
  "sources": [{ "path": "doc.pdf", "pages": "1-5" }],
  "include_document_map": true,
  "include_visual_enrichments": true,
  "max_visual_enrichments": 8,
  "include_full_text": false
}

PDF Reader MCP is designed as a full-fidelity intelligence layer for AI agents. Instead of simple text extraction, it provides an 'Agent Document Twin'—a combination of a document map, AST, and evidence indexes.

The recommended agent workflow follows three stages:

1. Profile and Map: Use read_pdf to profile the document and obtain the Agent Document Twin.
2. Search: Use search_pdf to find source-backed text matches (including snippets, offsets, and boxes) to minimize context usage.
3. Verify/Extract Evidence: Use pdf_evidence for focused follow-up operations like inspecting specific regions, rendering pages, or performing OCR when source-level proof is required.

This approach ensures agents move from broad understanding to specific, cited evidence without wasting context window on irrelevant text.